Difference between revisions of "Uno/Article/Multi-Thread Programming"

From Apache OpenOffice Wiki
< Uno
Jump to: navigation, search
(→‎C++ Example - Function only accepting thread-safe parameters: Fixed: Actually the function is environment specialized.)
m (Fixed: section level.)
Line 1: Line 1:
−
==Preface==
+
'''Preface''': The technology described in this article depends on the presence of the [[Uno/Effort/Creating the Uno Threading Framework|Uno Threading Framework]].
−
The technology described in this article depends on the presence of the [[Uno/Effort/Creating the Uno Threading Framework|Uno Threading Framework]].
+
  
−
==Multi-Thread Programming==
 
 
[[Uno]] is inherently multi-threaded, every Uno object may be accessed by multiple threads concurrently. The [[Uno/Spec/Threading Model|Uno threading framework]] provides support for simplifying multi-thread programming.
 
[[Uno]] is inherently multi-threaded, every Uno object may be accessed by multiple threads concurrently. The [[Uno/Spec/Threading Model|Uno threading framework]] provides support for simplifying multi-thread programming.
  
Line 12: Line 10:
 
Environments, mappings and object are at the heart of Uno, please read [[../Working with Environments, Mappings & Objects]] for an introduction.
 
Environments, mappings and object are at the heart of Uno, please read [[../Working with Environments, Mappings & Objects]] for an introduction.
  
−
===Environments===
+
==Environments==
 
Every [[Uno]] reference points to an object with particular characteristics. Among implementing a concrete interface and ABI, the object may have one or multiple "purposes" associated with it. The ABI and the "purposes" are expressed in the objects managing environment, e.g. the environment described by <code>"gcc3:unsafe"</code> manages objects with a GCC3 C++ ABI (if named properly, it would have been called "g++3" or "gpp3"), which are [[Uno/Term/Thread Unsafe|thread-unsafe]].
 
Every [[Uno]] reference points to an object with particular characteristics. Among implementing a concrete interface and ABI, the object may have one or multiple "purposes" associated with it. The ABI and the "purposes" are expressed in the objects managing environment, e.g. the environment described by <code>"gcc3:unsafe"</code> manages objects with a GCC3 C++ ABI (if named properly, it would have been called "g++3" or "gpp3"), which are [[Uno/Term/Thread Unsafe|thread-unsafe]].
  
Line 22: Line 20:
 
* <code>"java:affine"</code> - Environment for managing Java JNI objects which are [[Uno/Term/Thread Affine|thread-affine]].
 
* <code>"java:affine"</code> - Environment for managing Java JNI objects which are [[Uno/Term/Thread Affine|thread-affine]].
  
−
====Thread-Unsafe====
+
===Thread-Unsafe===
 
Any environment with an ":unsafe" in its description is a [[Uno/Term/Thread Unsafe|thread-unsafe]] environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the [[Uno/Spec/Thread Unsafety Bridge|thread-unsafety bridge]] for details.
 
Any environment with an ":unsafe" in its description is a [[Uno/Term/Thread Unsafe|thread-unsafe]] environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the [[Uno/Spec/Thread Unsafety Bridge|thread-unsafety bridge]] for details.
  
−
=====C++ Example - Entering a thread-unsafe environment=====
+
====C++ Example - Entering a thread-unsafe environment====
 
The semantics of "entering" or "invoking" a [[Uno/Term/Thread Unsafe|thread-unsafe]] environment are the same.  
 
The semantics of "entering" or "invoking" a [[Uno/Term/Thread Unsafe|thread-unsafe]] environment are the same.  
 
<code>[cpp]
 
<code>[cpp]
Line 42: Line 40:
 
Basically, only one thread at a time can have activated any "<ABI>:unsafe" environment in this process.
 
Basically, only one thread at a time can have activated any "<ABI>:unsafe" environment in this process.
  
−
====Thread-Affine====
+
===Thread-Affine===
 
Any environment with an ":affine" in its description is a thread-affine environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the [[Uno/Spec/Thread Affinity Bridge|thread-affinity bridge]] for details.
 
Any environment with an ":affine" in its description is a thread-affine environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the [[Uno/Spec/Thread Affinity Bridge|thread-affinity bridge]] for details.
  
 
Actually, the semantics of "entering" or "invoking" a thread-affine environment differ. Entering a thread-affine environment is only possible, if no thread has been associated with this environment yet, if a thread has already been associated, the entering thread waits until the associated thread  leaves (e.g. terminates) the environment. The associated thread may leave the moment, the last managed object has been released. After the current thread has been associated with this particular environment, all invocations of objects of this thread-affine environment get dispatched into this thread. In contrast, "invoking" a thread-affine environment creates a new, dedicated and hidden thread to be associated with it, if non has been associated yet, all invocations of objects are then dispatched to this (new) thread.
 
Actually, the semantics of "entering" or "invoking" a thread-affine environment differ. Entering a thread-affine environment is only possible, if no thread has been associated with this environment yet, if a thread has already been associated, the entering thread waits until the associated thread  leaves (e.g. terminates) the environment. The associated thread may leave the moment, the last managed object has been released. After the current thread has been associated with this particular environment, all invocations of objects of this thread-affine environment get dispatched into this thread. In contrast, "invoking" a thread-affine environment creates a new, dedicated and hidden thread to be associated with it, if non has been associated yet, all invocations of objects are then dispatched to this (new) thread.
  
−
=====C++ Example - Entering a thread-affine environment=====
+
====C++ Example - Entering a thread-affine environment====
 
In the following example, the newly created instance of "MyUnoObject" is guaranteed to only be called by the creating thread. When trying to leave the thread-affine environment, the d'tor of the "affineGuard" will block as long as objects are managed by this environment, basically ensuring that the objects are still reachable.
 
In the following example, the newly created instance of "MyUnoObject" is guaranteed to only be called by the creating thread. When trying to leave the thread-affine environment, the d'tor of the "affineGuard" will block as long as objects are managed by this environment, basically ensuring that the objects are still reachable.
  
Line 64: Line 62:
 
</code>
 
</code>
  
−
=====C++ Example - Invoking a thread-affine environment=====
+
====C++ Example - Invoking a thread-affine environment====
 
The example shows, how to correctly invoke a thread-affine environment, as always, all objects need to be managed properly by the managing environments.
 
The example shows, how to correctly invoke a thread-affine environment, as always, all objects need to be managed properly by the managing environments.
 
<code>[cpp]
 
<code>[cpp]
Line 88: Line 86:
 
</code>
 
</code>
  
−
====Thread-Safe====
+
===Thread-Safe===
 
Any environment with neither ":unsafe" nor ":affine" in its description is a thread-safe environment. Objects managed by such an environment may very well be called directly by concurrent threads. Examples for thread-safe environments are <code>"gcc3"</code> or <code>"java"</code>, and also <code>"gcc3:debug"</code> or <code>"uno:debug"</code>.
 
Any environment with neither ":unsafe" nor ":affine" in its description is a thread-safe environment. Objects managed by such an environment may very well be called directly by concurrent threads. Examples for thread-safe environments are <code>"gcc3"</code> or <code>"java"</code>, and also <code>"gcc3:debug"</code> or <code>"uno:debug"</code>.
  
−
===Helpers===
+
==Helpers==
−
====C++ Shield Helpers====
+
===C++ Shield Helpers===
 
The "shield" helpers basically allow to shortcut the mapping of an object  
 
The "shield" helpers basically allow to shortcut the mapping of an object  
 
* from the current (typically thread-unsafe or thread-affine) environment, to the thread-safe C++ environment,
 
* from the current (typically thread-unsafe or thread-affine) environment, to the thread-safe C++ environment,
Line 99: Line 97:
 
Please have a look a the [[Uno/Cpp/Spec/Shield Helpers|specification for the shield helpers]] for more details.
 
Please have a look a the [[Uno/Cpp/Spec/Shield Helpers|specification for the shield helpers]] for more details.
  
−
======C++ Example - Map Object to Thread-Safe======
+
=====C++ Example - Map Object to Thread-Safe=====
 
Do the mapping by hand:
 
Do the mapping by hand:
 
<code>[cpp]
 
<code>[cpp]
Line 123: Line 121:
 
</code>
 
</code>
  
−
======C++ Example - Map Object from Thread-Safe======
+
=====C++ Example - Map Object from Thread-Safe=====
 
Do the mapping by hand:
 
Do the mapping by hand:
 
<code>[cpp]
 
<code>[cpp]
Line 147: Line 145:
 
</code>
 
</code>
  
−
======C++ Example - Map <code>uno::Any</code> to Thread-Safe======
+
=====C++ Example - Map <code>uno::Any</code> to Thread-Safe=====
 
Do the mapping by hand:
 
Do the mapping by hand:
 
<code>[cpp]
 
<code>[cpp]
Line 172: Line 170:
 
</code>
 
</code>
  
−
======C++ Example - Map <code>uno::Any</code> from Thread-Safe======
+
=====C++ Example - Map <code>uno::Any</code> from Thread-Safe=====
 
Do the mapping by hand:
 
Do the mapping by hand:
 
<code>[cpp]
 
<code>[cpp]
Line 197: Line 195:
 
</code>
 
</code>
  
−
===Objects===
+
==Objects==
 
Going to implement an UNO object, you need to decide on the threading architecture. You basically have the following choices, the object can either be
 
Going to implement an UNO object, you need to decide on the threading architecture. You basically have the following choices, the object can either be
 
* [[Uno/Term/Thread Unsafe|thread-unsafe]], or
 
* [[Uno/Term/Thread Unsafe|thread-unsafe]], or
Line 203: Line 201:
 
* [[Uno/Term/Thread Affine|thread-affine]].
 
* [[Uno/Term/Thread Affine|thread-affine]].
  
−
====Architecture====
+
===Architecture===
−
=====Thread-Unsafe=====
+
====Thread-Unsafe====
 
[[Uno/Term/Thread Unsafe|Thread unsafe]] is the choice for most cases. Actually leaving proper synchronization of method calls to the [[Uno/Spec/Runtime|runtime]].  
 
[[Uno/Term/Thread Unsafe|Thread unsafe]] is the choice for most cases. Actually leaving proper synchronization of method calls to the [[Uno/Spec/Runtime|runtime]].  
  
−
=====Thread-Safe=====
+
====Thread-Safe====
 
There are only rare cases where you actually want to implement your object [[Uno/Term/Thread Safe|thread-safe]]. Either
 
There are only rare cases where you actually want to implement your object [[Uno/Term/Thread Safe|thread-safe]]. Either
 
* your object should or must allow the parallel execution of some of its methods, or
 
* your object should or must allow the parallel execution of some of its methods, or
Line 218: Line 216:
 
'''Note:''' Scalability may be achieved by the introduction of [[Uno/Spec/Named Environment|named environments]], actually allowing any number of [[Uno/Term/Thread Unsafe|thread-unsafe]] [[Uno/Spec/Purpose Environment|purpose environments]] to exist simultaneously and to be activated by multiple threads in parallel.
 
'''Note:''' Scalability may be achieved by the introduction of [[Uno/Spec/Named Environment|named environments]], actually allowing any number of [[Uno/Term/Thread Unsafe|thread-unsafe]] [[Uno/Spec/Purpose Environment|purpose environments]] to exist simultaneously and to be activated by multiple threads in parallel.
  
−
=====Thread-Affine=====
+
====Thread-Affine====
 
[[Uno/Term/Thread Affine|Thread-affine]] objects are rare. In OOo they are needed to encapsulate the Win32 respectively the OLE/COM thread affinity.
 
[[Uno/Term/Thread Affine|Thread-affine]] objects are rare. In OOo they are needed to encapsulate the Win32 respectively the OLE/COM thread affinity.
  
−
====Implementation====
+
===Implementation===
 
Every type of object needs to be implemented somewhere. Dependent on the location, different actions need to be taken, to ensure correct usage of the object with respect to its threading architecture.
 
Every type of object needs to be implemented somewhere. Dependent on the location, different actions need to be taken, to ensure correct usage of the object with respect to its threading architecture.
  
−
=====Components=====
+
====Components====
 
The easiest way to implement an object is a component, as a component actively provides the managing environments of its objects. That means, that components do not need to ensure proper mapping etc., this is all taken care of by the component loader already.
 
The easiest way to implement an object is a component, as a component actively provides the managing environments of its objects. That means, that components do not need to ensure proper mapping etc., this is all taken care of by the component loader already.
  
−
======C++ Example - A thread-unsafe component======
+
=====C++ Example - A thread-unsafe component=====
 
The <code>component_getImplementationEnvironment</code> function for a component does return the single managing environment for all objects provided by this component. The implementation of this function for a [[Uno/Term/Thread Unsafe|thread-unsafe]] component may look like this:
 
The <code>component_getImplementationEnvironment</code> function for a component does return the single managing environment for all objects provided by this component. The implementation of this function for a [[Uno/Term/Thread Unsafe|thread-unsafe]] component may look like this:
 
<code>[cpp]
 
<code>[cpp]
Line 239: Line 237:
 
</code>
 
</code>
  
−
======C++ Example - A thread variable component======
+
=====C++ Example - A thread variable component=====
 
A component implementing [[Uno/Term/Thread Safe|thread-safe]] and [[Uno/Term/Thread Transparent|thread-transparent]] objects may want to utilize these capabilities by avoiding any mapping, this can be done by implementing the <code>component_getImplementationEnvironmentExt</code> function, instead of the <code>component_getImplementationEnvironment</code> function. The implementation of this function for a thread variable component may look like this:
 
A component implementing [[Uno/Term/Thread Safe|thread-safe]] and [[Uno/Term/Thread Transparent|thread-transparent]] objects may want to utilize these capabilities by avoiding any mapping, this can be done by implementing the <code>component_getImplementationEnvironmentExt</code> function, instead of the <code>component_getImplementationEnvironment</code> function. The implementation of this function for a thread variable component may look like this:
 
<code>[cpp]
 
<code>[cpp]
Line 256: Line 254:
 
</code>
 
</code>
  
−
=====Libraries&Applications=====
+
====Libraries&Applications====
 
Uno objects may as well be implemented in libraries or applications. Caller and callee must agree one the managing environment for passed or returned objects, to not break [[Uno/Term/Environment Integrity]].
 
Uno objects may as well be implemented in libraries or applications. Caller and callee must agree one the managing environment for passed or returned objects, to not break [[Uno/Term/Environment Integrity]].
  
Line 263: Line 261:
 
'''Note: ''' No convention, except documentation, has yet been introduced to identify any environment specialization of a function.
 
'''Note: ''' No convention, except documentation, has yet been introduced to identify any environment specialization of a function.
  
−
======C++ Example - Function always returning a thread-safe object======
+
=====C++ Example - Function always returning a thread-safe object=====
 
The following example shows a function always returning an appropriate (correct ABI and purpose) object of type XInterface. For this function to work properly, the client must have activated the appropriate environment, as the <code>uno::Reference</code> is only partly (namely ABI) specialized.
 
The following example shows a function always returning an appropriate (correct ABI and purpose) object of type XInterface. For this function to work properly, the client must have activated the appropriate environment, as the <code>uno::Reference</code> is only partly (namely ABI) specialized.
  
Line 313: Line 311:
 
</code>
 
</code>
  
−
======C++ Example - Function only accepting thread-safe parameters======
+
=====C++ Example - Function only accepting thread-safe parameters=====
 
In the following example, the called function gets a thread-safe parameter, which needs to be mapped appropriately to the <code>"c++:unsafe"</code> environment, to be able to pass a [[Uno/Term/Thread Unsafe|thread-unsafe]] object to the <code>set</code> method of the parameter. For the function to work properly, the client must be in the thread-safe environment.
 
In the following example, the called function gets a thread-safe parameter, which needs to be mapped appropriately to the <code>"c++:unsafe"</code> environment, to be able to pass a [[Uno/Term/Thread Unsafe|thread-unsafe]] object to the <code>set</code> method of the parameter. For the function to work properly, the client must be in the thread-safe environment.
  
Line 349: Line 347:
 
</code>
 
</code>
  
−
===Threads===
+
==Threads==
 
Thinking about threads, thread related environments and Uno objects, we roughly can identify the following types:
 
Thinking about threads, thread related environments and Uno objects, we roughly can identify the following types:
 
* Asynchronous threads, which run in the thread-safe environment.
 
* Asynchronous threads, which run in the thread-safe environment.
Line 356: Line 354:
 
Mixed types are certainly possible.
 
Mixed types are certainly possible.
  
−
====Asynchronous====
+
===Asynchronous===
 
The asynchronous thread holds one or multiple references to thread-safe Uno objects. During its execution it may call on one or another of these objects. Every call may compete with any another threads call. In case a called object is not thread-safe (e.g. thread-unsafe or thread-affine), the appropriate environments becomes activated implicitly before the call, and becomes deactivated implicitly after the call.
 
The asynchronous thread holds one or multiple references to thread-safe Uno objects. During its execution it may call on one or another of these objects. Every call may compete with any another threads call. In case a called object is not thread-safe (e.g. thread-unsafe or thread-affine), the appropriate environments becomes activated implicitly before the call, and becomes deactivated implicitly after the call.
  
−
====Synchronous====
+
===Synchronous===
 
The synchronous thread holds one or multiple references to thread-unsafe or thread-affine objects. Before actually invoking any calls, the thread does activate the managing environment of hold objects. The calls are therefor not competing and the call sequence is atomic. After a sequence of calls, the thread deactivates the managing environment.
 
The synchronous thread holds one or multiple references to thread-unsafe or thread-affine objects. Before actually invoking any calls, the thread does activate the managing environment of hold objects. The calls are therefor not competing and the call sequence is atomic. After a sequence of calls, the thread deactivates the managing environment.
  
−
====Hidden====
+
===Hidden===
 
The hidden thread is an implementation detail of a particular object only. Proper synchronization (e.g. acquiring / releasing mutexes) is taken care of by the implementer.
 
The hidden thread is an implementation detail of a particular object only. Proper synchronization (e.g. acquiring / releasing mutexes) is taken care of by the implementer.
  
−
====C++ Examples====
+
===C++ Examples===
−
=====Asynchronous Thread=====
+
====Asynchronous Thread====
 
Do not activate any environment explicitly, just run in the thread-safe environment. Only implicitly activate other environments when activating mapped objects (e.g. thread-unsafe object).
 
Do not activate any environment explicitly, just run in the thread-safe environment. Only implicitly activate other environments when activating mapped objects (e.g. thread-unsafe object).
  
Line 388: Line 386:
 
</code>
 
</code>
  
−
=====Synchronous Thread=====
+
====Synchronous Thread====
 
Just enter the environment and do all calls while being in it. Obviously, releasing the objects also needs to be done in the environment.
 
Just enter the environment and do all calls while being in it. Obviously, releasing the objects also needs to be done in the environment.
 
<code>[cpp]
 
<code>[cpp]

Revision as of 11:47, 1 September 2006

Preface: The technology described in this article depends on the presence of the Uno Threading Framework.

Uno is inherently multi-threaded, every Uno object may be accessed by multiple threads concurrently. The Uno threading framework provides support for simplifying multi-thread programming.

There are actually three things important to know about, when doing multi-threading and Uno. These are

  • dedicated thread related environments,
  • how to use these environments when doing particular implementations,
  • and certainly, how to use threads WRT Uno objects.

Environments, mappings and object are at the heart of Uno, please read Uno/Article/Working with Environments, Mappings & Objects for an introduction.

Environments

Every Uno reference points to an object with particular characteristics. Among implementing a concrete interface and ABI, the object may have one or multiple "purposes" associated with it. The ABI and the "purposes" are expressed in the objects managing environment, e.g. the environment described by "gcc3:unsafe" manages objects with a GCC3 C++ ABI (if named properly, it would have been called "g++3" or "gpp3"), which are thread-unsafe.

The Uno threading model brings thread-affine purpose environments and thread-unsafe purpose environments. Objects not belonging to one of these two purpose environments are assumed to be thread-safe.

Examples:

  • "gcc3:unsafe" - Environment for managing objects with a GCC3 C++ ABI, which are thread-unsafe.
  • "java" - Environment for managing Java JNI objects, without any further characteristics, therefor the managed objects have to be thread-safe.
  • "java:affine" - Environment for managing Java JNI objects which are thread-affine.

Thread-Unsafe

Any environment with an ":unsafe" in its description is a thread-unsafe environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the thread-unsafety bridge for details.

C++ Example - Entering a thread-unsafe environment

The semantics of "entering" or "invoking" a thread-unsafe environment are the same. [cpp] ... { 

 // Enter the "gcc3:unsafe" environment
 cppu::EnvGuard unsafeGuard(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:unsafe"))));
 // Now we can safely directly call on any object belonging to this environment,
 // no second thread can enter this environment in parallel
 pObj->doSomething();

 // We implicity leave the "gcc3:unsafe" environment

} ... Basically, only one thread at a time can have activated any "<ABI>:unsafe" environment in this process.

Thread-Affine

Any environment with an ":affine" in its description is a thread-affine environment. Objects managed by such an environment may not be called directly by multiple threads. See the specification of the thread-affinity bridge for details.

Actually, the semantics of "entering" or "invoking" a thread-affine environment differ. Entering a thread-affine environment is only possible, if no thread has been associated with this environment yet, if a thread has already been associated, the entering thread waits until the associated thread leaves (e.g. terminates) the environment. The associated thread may leave the moment, the last managed object has been released. After the current thread has been associated with this particular environment, all invocations of objects of this thread-affine environment get dispatched into this thread. In contrast, "invoking" a thread-affine environment creates a new, dedicated and hidden thread to be associated with it, if non has been associated yet, all invocations of objects are then dispatched to this (new) thread.

C++ Example - Entering a thread-affine environment

In the following example, the newly created instance of "MyUnoObject" is guaranteed to only be called by the creating thread. When trying to leave the thread-affine environment, the d'tor of the "affineGuard" will block as long as objects are managed by this environment, basically ensuring that the objects are still reachable.

[cpp] class MyUnoObject ...;

... { 

 cppu::EnvGuard affineGuard(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
 
 smgr->createInstanceWithArguments(new MyUnoObject());

 // the implicit "leave" call blocks, until all objects managed by "gcc3:affine" are released.

} ...

C++ Example - Invoking a thread-affine environment

The example shows, how to correctly invoke a thread-affine environment, as always, all objects need to be managed properly by the managing environments. [cpp] class MyUnoObject ...;

void doSomething(va_list param) { 

 XMultiServiceFactory * pSmgr = va_arg(param, XMultiServiceFactory *);
 pSmgr->createInstanceWithArguments(new MyUnoObject());

}

... { 

 uno::Environment affineEnv(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));

 Mapping curr2affine(uno::getCurrentEnvironment(), affineEnv);

 void * affineSmgr = curr2affine.mapInterface(smgr, typeof(smgr));
 affineEnv.invoke(s_doSomething, affineSmgr);
 affineEnv.get()->pExtEnv->releaseInterface(affineSmgr);

} ...

Thread-Safe

Any environment with neither ":unsafe" nor ":affine" in its description is a thread-safe environment. Objects managed by such an environment may very well be called directly by concurrent threads. Examples for thread-safe environments are "gcc3" or "java", and also "gcc3:debug" or "uno:debug".

Helpers

C++ Shield Helpers

The "shield" helpers basically allow to shortcut the mapping of an object

  • from the current (typically thread-unsafe or thread-affine) environment, to the thread-safe C++ environment,
  • from the thread-safe C++ environment to the current (typically thread-unsafe or thread-affine) environment.

Please have a look a the specification for the shield helpers for more details.

C++ Example - Map Object to Thread-Safe

Do the mapping by hand: [cpp] ... uno::XInterface * pUnsafe_Object ...; uno::Mapping curr2safe(uno::getCurrentEnvironment(), 

                      rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(CPPU_STRINGIFY(CPPU_ENV))));

uno::XInterface * pSafe_Object = reinterpret_cast<uno::XInterface *>( 

                                   curr2safe.mapInterface(
                                     pObject, 
                                     getCppuType((cssu::Reference<XInterface> *)NULL)
                                   )
                                );

... Can be simply replaced with: [cpp] ... uno::XInterface * pUnsafe_Object ...; uno::XInterface * pSafe_Object = cppu::shield(pUnsafe_Object); ...

C++ Example - Map Object from Thread-Safe

Do the mapping by hand: [cpp] ... uno::XInterface * pSafe_Object ...; uno::Mapping safe2curr(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(CPPU_STRINGIFY(CPPU_ENV))), 

                      uno::getCurrentEnvironment());

uno::XInterface * pUnsafe_Object = reinterpret_cast<uno::XInterface *>( 

                                    safe2curr.mapInterface(
                                      pObject, 
                                      getCppuType((cssu::Reference<uno::XInterface> *)NULL)
                                    )
                                  );

... Can be simply replaced with: [cpp] ... uno::XInterface * pSafe_Object ...; uno::XInterface * pUnsafe_Object = cppu::unshield(pSafe_Object); ...

C++ Example - Map uno::Any to Thread-Safe

Do the mapping by hand: [cpp] ... uno::Any unsafeAny = ...

uno::Mapping curr2safe(uno::getCurrentEnvironment(), 

                      rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(CPPU_STRINGIFY(CPPU_ENV))));

uno::Any safeAny; uno_any_destruct(&safeAny, (uno_ReleaseFunc)uno::cpp_release); uno_type_any_constructAndConvert(&safeAny, 

                                const_cast<void *>(unsafeAny.getValue()),
                                unsafeAny.getValueTypeRef(),
                                curr2safe.get());

... Can be simply replaced with: [cpp] ... uno::Any unsafeAny = ... uno::Any safeAny(cppu::shieldAny(unsafeAny)); ...

C++ Example - Map uno::Any from Thread-Safe

Do the mapping by hand: [cpp] ... uno::Any safeAny = ...

uno::Mapping safe2curr(uno::getCurrentEnvironment(), 

                      rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(CPPU_STRINGIFY(CPPU_ENV))));

uno::Any unsafeAny; uno_any_destruct(&unsafeAny, (uno_ReleaseFunc)uno::cpp_release); uno_type_any_constructAndConvert(&unsafeAny, 

                                const_cast<void *>(safeAny.getValue()),
                                safeAny.getValueTypeRef(),
                                safe2curr.get());

... Can be simply replaced with: [cpp] ... uno::Any safeAny = ... uno::Any unsafeAny(cppu::unshieldAny(safeAny)); ...

Objects

Going to implement an UNO object, you need to decide on the threading architecture. You basically have the following choices, the object can either be

Architecture

Thread-Unsafe

Thread unsafe is the choice for most cases. Actually leaving proper synchronization of method calls to the runtime.

Thread-Safe

There are only rare cases where you actually want to implement your object thread-safe. Either

  • your object should or must allow the parallel execution of some of its methods, or
  • you want to avoid any overhead associated with leaving synchronization to the runtime.

One case, where your component must allow the parallel execution of methods is, when you want to be able to abort a running invocation. Uno currently does not offer a mechanism to do this generically, so that particular objects must provide dedicated methods for abortion. An example for this is the util/io/Acceptor implementation.

The overhead for automatic synchronization only affects inter-environment calls. The threading architecture of a particular application should be designed in a way, that closely connected objects happen to exist in the same environment. Basically ensuring a low inter-environment call frequency, converting any potential advantage of self synchronized methods to the reverse.

Note: Scalability may be achieved by the introduction of named environments, actually allowing any number of thread-unsafe purpose environments to exist simultaneously and to be activated by multiple threads in parallel.

Thread-Affine

Thread-affine objects are rare. In OOo they are needed to encapsulate the Win32 respectively the OLE/COM thread affinity.

Implementation

Every type of object needs to be implemented somewhere. Dependent on the location, different actions need to be taken, to ensure correct usage of the object with respect to its threading architecture.

Components

The easiest way to implement an object is a component, as a component actively provides the managing environments of its objects. That means, that components do not need to ensure proper mapping etc., this is all taken care of by the component loader already.

C++ Example - A thread-unsafe component

The component_getImplementationEnvironment function for a component does return the single managing environment for all objects provided by this component. The implementation of this function for a thread-unsafe component may look like this: [cpp] extern "C" void SAL_CALL component_getImplementationEnvironment( 

 sal_Char        const ** ppEnvTypeName, 
 uno_Environment       ** ppEnv

) { 

 *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME ":unsafe";

}

C++ Example - A thread variable component

A component implementing thread-safe and thread-transparent objects may want to utilize these capabilities by avoiding any mapping, this can be done by implementing the component_getImplementationEnvironmentExt function, instead of the component_getImplementationEnvironment function. The implementation of this function for a thread variable component may look like this: [cpp] extern "C" void SAL_CALL component_getImplementationEnvironmentExt( 

 sal_Char        const ** ppEnvTypeName, 
 uno_Environment       ** ppEnv,
 sal_Char        const  * pImplName,
 uno_Environment        * pSrcEnv

) { 

 rtl::OUString envName(RTL_CONSTASCII_USTRINGPARAM(CPPU_CURRENT_LANGUAGE_BINDING));
 envName += cppu::EnvDcp_getPurpose(Environment(pSrcEnv).getTypeName());

 uno_getEnvironment(ppEnv, envName.pData, NULL);

}

Libraries&Applications

Uno objects may as well be implemented in libraries or applications. Caller and callee must agree one the managing environment for passed or returned objects, to not break Uno/Term/Environment Integrity.

All public Uno libraries do return appropriate objects, the implementations of the API are only partly (namely ABI) specialized and dynamically map the return or paramter objects.

Note: No convention, except documentation, has yet been introduced to identify any environment specialization of a function.

C++ Example - Function always returning a thread-safe object

The following example shows a function always returning an appropriate (correct ABI and purpose) object of type XInterface. For this function to work properly, the client must have activated the appropriate environment, as the uno::Reference is only partly (namely ABI) specialized.

Callee: [cpp] // This function is environment specialized on "c++". uno::Reference<uno::XInterface> create_threadSafeObject(void) { 

 uno:Reference<uno::XInterface>  result_Obj;

 // We may want to ensure that we are in the "c++" only environment.
 ensure(uno::getCurrent().getTypeName() == rtl::OUString(RTL_CONSTASCII_PARAM("c++")));

 // We may want to open a new scope, to ensure that "result_Obj" does
 // not get destructed while "c++:unsafe" is active.
 {
   // We activate (enter) the "c++:unsafe" environment.
   // Note: Any other environment suiteable for "MyUnsafeObject" would work as well.
   cppu::EnvGuard unsafeGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_PARAM("c++:unsafe"))));

   // This reference points to a "thread-unsafe" object.
   Reference<uno::XInterface> unsafeEnv_Obj(new MyUnsafeObject());

   // We may do some activations on "unsafeEnv_Obj".
   unsafeEnv_Obj->doThis();
   unsafeEnv_Obj->doThat();

   // We "shield" the object and assign it to "result_Obj"
   result_Obj.set(cppu::shield(unsafeEnv_Obj), SAL_NO_ACQUIRE);

   // We may _not_ activate result_obj, as we are still in the "c++:unsafe" environment.
 }

 // Using "result_obj" is "safe" here.
 return result_Obj;

}

Caller: [cpp] ... { 

 // We leave all "purpose" environments here, as "create_threadSafeObject" returns
 // "c++" (thread-safe) objects only.
 cppu::AntiEnvGuard antiGuard;

 uno::Reference safe_obj(create_threadSafeObject());

} ...

C++ Example - Function only accepting thread-safe parameters

In the following example, the called function gets a thread-safe parameter, which needs to be mapped appropriately to the "c++:unsafe" environment, to be able to pass a thread-unsafe object to the set method of the parameter. For the function to work properly, the client must be in the thread-safe environment.

Callee: [cpp] // This function is environment specialized on "c++". void setUnsafeObject(uno::Reference<...> const & rObj) { 

 // We may want to ensure that we are in the "c++" only environment.
 ensure(uno::getCurrent().getTypeName() == rtl::OUString(RTL_CONSTASCII_PARAM("c++")));

 // We now activate (enter) the "c++:unsafe" environment.
 // Note: Any other environment suiteable for "MyUnsafeObject" would work as well.
 cppu::EnvGuard unsafeGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_PARAM("c++:unsafe"))));

 // We "unshield" the parameter.
 Reference<type> unsafeEnv_Obj.set(cppu::unshield(rObj), SAL_NO_ACQUIRE);

 // MyUnsafeObj has a C++ ABI and is thread-unsafe
 unsafeEnv_Obj->set(new MyUnsafeObject());

}

Caller: [cpp] ... { 

 // We leave all "purpose" environments here, as "setUnsafeObject" accepts
 // "c++" (thread-safe) objects only.
 cppu::AntiEnvGuard antiGuard;

 uno::Reference<...> obj(...);
 setUnsafeObj(obj);

} ...

Threads

Thinking about threads, thread related environments and Uno objects, we roughly can identify the following types:

  • Asynchronous threads, which run in the thread-safe environment.
  • Synchronous threads, which run in a thread-unsafe or thread-affine environment.
  • Hidden threads, which run in an objects implementation only.

Mixed types are certainly possible.

Asynchronous

The asynchronous thread holds one or multiple references to thread-safe Uno objects. During its execution it may call on one or another of these objects. Every call may compete with any another threads call. In case a called object is not thread-safe (e.g. thread-unsafe or thread-affine), the appropriate environments becomes activated implicitly before the call, and becomes deactivated implicitly after the call.

Synchronous

The synchronous thread holds one or multiple references to thread-unsafe or thread-affine objects. Before actually invoking any calls, the thread does activate the managing environment of hold objects. The calls are therefor not competing and the call sequence is atomic. After a sequence of calls, the thread deactivates the managing environment.

Hidden

The hidden thread is an implementation detail of a particular object only. Proper synchronization (e.g. acquiring / releasing mutexes) is taken care of by the implementer.

C++ Examples

Asynchronous Thread

Do not activate any environment explicitly, just run in the thread-safe environment. Only implicitly activate other environments when activating mapped objects (e.g. thread-unsafe object).

[cpp] class MyThread : public Thread { 

 uno::Reference<...> m_safe_obj; // this points to a "thread-safe" object

protected: 

 virtual void SAL_CALL run()
 {
   m_safe_obj.doThis();
   m_safe_obj.doThat();
 }

public: 

 MyThread(uno::Reference<XInterface> const & xInterface)
   : m_xInterface(cppu::shield(xInterface), SAL_NO_ACQUIRE)
 {}

};

Synchronous Thread

Just enter the environment and do all calls while being in it. Obviously, releasing the objects also needs to be done in the environment. [cpp] class MyThread : public Thread { 

 uno::Environment    m_refEnv;
 uno::Reference<...> m_unsafe_obj;

 static void s_doSomething(va_list param)
 {
   MyThread * pMyThread = va_arg(param, MyThread *);
   pMyThread->m_unsafe_obj.clear();
 }

 static void s_doSomething(va_list param)
 {
   MyThread * pMyThread = va_arg(param, MyThread *);
   // do not do any slow/blocking operations here, as the target environment is
   // currently activated, and no other thread may enter at the moment...
   m_unsafe_obj->doThis();
   m_unsafe_obj->doThat();  
   pMyThread->i_doSomething();
 }

public: 

 MyThread(uno::Reference<XInterface> const & xInterface);
   : m_xInterface(xInterface), m_refEnv(uno::getCurrentEnvironment());
 {}

 MyThread::~MyThread() 
 {
   // the object needs to be released in the managing environment.
   // unfortunately, there is not yet a SAL_NO_RELEASE
   m_refEnv.invoke(s_clear, this);
 }

 void doSomething()
 {
   m_refEnv.invoke(s_doSomething, this);
 }

};

Specifications

The relevant specifications can be found here:

In particular:

See also

Retrieved from "https://wiki.openoffice.org/w/index.php?title=Uno/Article/Multi-Thread_Programming&oldid=15951"
Personal tools