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

From Apache OpenOffice Wiki
< Uno
Jump to: navigation, search
(Create new section "Helpers" and moved shield helpers.)
m (Synchronous Thread)
 
(32 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Preface==
+
{{Uno/Note}} The technology described in this article depends on the presence of the [[Uno/Effort/Binary/Extend Threading-Model|extended Binary Uno threading-model]], which has been integrated into URE 1.3 (SRC680_m212).
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-Model]] 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.
+
  
There are actually three things important to know about, when doing multi-threading and Uno. These are  
+
There are actually three things important to know about, when doing multi-threading with [[Uno]]. These are  
* dedicated thread related environments,
+
* the dedicated, thread related [[Uno/Spec/Environment|environments]],
* how to use these environments when doing particular implementations,
+
* how to use these [[Uno/Spec/Environment|environments]] when creating particular implementations,
* and certainly, how to use threads WRT Uno objects.
+
* and certainly, how to use threads wrt. Uno objects.
  
Environments, mappings and object are at the heart of Uno, please read [[../Working with Environments, Mappings & Objects]] for an introduction.
+
[[Uno/Spec/Environment|Environments]], [[Uno/Spec/Mapping|mappings]] and [[Uno/Spec/Object|objects]] are at the heart of [[Uno]], please read [[../Working with Environments, Mappings & Objects|Working with Environments, Mappings & Objects]] for an introduction.
  
===Environments===
+
==Objects==
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]].
+
Going to implement an [[Uno/Spec/Object|Uno object]], you need to decide on the [[Uno/Term/Threading-Architecture|threading-architecture]]. You basically have the following choices, the object can either be
 +
* [[Uno/Term/Thread Unsafe|thread-unsafe]], or
 +
* [[Uno/Term/Thread Safe|thread-safe]], or
 +
* [[Uno/Term/Thread Affine|thread-affine]].
 +
 
 +
===Purpose===
 +
====[[Uno/Term/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|Uno runtime]].
 +
 
 +
====[[Uno/Term/Thread Safe|Thread-Safe]]====
 +
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
 +
* you want to avoid any overhead associated with leaving synchronization to the [[Uno/Spec/Runtime|Uno runtime]].
 +
 
 +
One case, where your object must allow the parallel execution of methods is, when you want to be able to abort a running invocation of one of its methods. [[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 [http://util.openoffice.org/source/browse/util/io/source/acceptor/ util/io/Acceptor] implementation.
 +
 
 +
The overhead for automatic synchronization only affects inter-[[Uno/Spec/Environment|environment]] calls. The [[Uno/Term/Threading-Architecture|threading-architecture]] of a particular application should be designed in a way, that closely connected objects happen to exist in the same [[Uno/Spec/Environment|Uno 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 [[../Working with Environments, Mappings & Objects#Naming|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 independently.
 +
 
 +
====[[Uno/Term/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 [[Uno/Term/Thread Affine|thread-affinity]]. See [[Effort/Make_VCL_Thread-Transparent|Make Vcl Thread-Transparent]] for details.
 +
 
 +
===Implementation===
 +
Every 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 [[Uno/Term/Threading-Architecture|threading-architecture]].
 +
 
 +
====Components====
 +
The easiest way to implement an object is a [[Uno/Spec/Component|component]], as a component actively provides the managing environments of its objects. This 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 [[Uno/Term/Thread Unsafe|thread-unsafe]] Component=====
 +
The <code>component_getImplementationEnvironment</code> function of a component does return the single managing environment for all objects provided by this component. The implementation of this function for [[Uno/Term/Thread Unsafe|thread-unsafe]] objects may look like this:
 +
<source lang="cpp">
 +
extern "C" void SAL_CALL component_getImplementationEnvironment(
 +
  sal_Char        const ** ppEnvTypeName,
 +
  uno_Environment      ** ppEnv
 +
)
 +
{
 +
  *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME ":unsafe";
 +
}
 +
</source>
 +
 
 +
=====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:
 +
<source lang="cpp">
 +
#include "cppu/EnvDcp.hxx"
 +
 
 +
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);
 +
}
 +
</source>
 +
 
 +
====Libraries&Applications====
 +
[[Uno/Spec/Uno Object|Uno objects]] may as well be implemented in libraries or applications. Caller and callee must agree one the managing [[Uno/Spec/Environment|environment]] for passed or returned objects, to not break [[Uno/Term/Environment Integrity]].
 +
 
 +
All public Uno libraries always do return appropriate objects, the implementations of the API are only [[Uno/Term/Object Binary Interface|OBI]] specialized and dynamically map the return or parameter objects according to the callers (purpose) [[Uno/Spec/Environment|environment]].
 +
 
 +
{{Uno/Note}} No convention, except documentation, has yet been introduced to identify any environment specialization of a function.
 +
 
 +
=====C++ Example - Function always returning a [[Uno/Term/Thread Safe|thread-safe]] Object=====
 +
The following example shows a function always returning a [[Uno/Term/Thread Safe|thread-safe]] object, while the objects implementation itself is [[Uno/Term/Thread Unsafe|thread-unsafe]]. For this function to work properly, the client must have left any [[Uno/Term/Thread Unsafe|thread-unsafe]] environment.
 +
 
 +
Callee:
 +
<source lang="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.
 +
  assert(uno::Environment::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.
 +
    uno::Reference<uno::XInterface> unsafeEnv_Obj(new MyUnsafeObject());
 +
 
 +
    // We may do some invocations on "unsafeEnv_Obj" while being in the "unsafe" environment.
 +
    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 fine here.
 +
  return result_Obj;
 +
}
 +
</source>
 +
 
 +
Caller:
 +
<source lang="cpp">
 +
...
 +
{
 +
  // We just leave all "purpose" environments here, as "create_threadSafeObject" returns
 +
  // "c++" (thread-safe) objects only.
 +
  cppu::AntiEnvGuard antiGuard;
 +
 
 +
  uno::Reference safe_obj(create_threadSafeObject());
 +
}
 +
...
 +
</source>
 +
 
 +
=====C++ Example - Function only accepting [[Uno/Term/Thread Safe|thread-safe]] Parameters=====
 +
In the following example, the called function gets a [[Uno/Term/Thread Safe|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 [[Uno/Term/Thread Safe|thread-safe]] environment.
 +
 
 +
Callee:
 +
<source lang="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.
 +
  assert(uno::Environment::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.
 +
  uno::Reference<...> unsafeEnv_Obj.set(cppu::unshield(rObj), SAL_NO_ACQUIRE);
 +
 
 +
  // MyUnsafeObj has a C++ OBI and is thread-unsafe
 +
  unsafeEnv_Obj->set(new MyUnsafeObject());
 +
}
 +
</source>
 +
 
 +
Caller:
 +
<source lang="cpp">
 +
...
 +
{
 +
  // We leave all "purpose" environments here, as "setUnsafeObject" accepts
 +
  // "c++" (thread-safe) objects only.
 +
  cppu::AntiEnvGuard antiGuard;
 +
 
 +
  uno::Reference<...> obj(...);
 +
  setUnsafeObj(obj);
 +
}
 +
...
 +
</source>
 +
 
 +
==[[Uno/Spec/Environment|Environments]]==
 +
Every [[Uno]] reference points to an object with particular characteristics. Among implementing a concrete interface and [[Uno/Term/Object Binary Interface|Object Binary Interface (OBI)]], the object may have one or multiple "purposes" associated with it. The [[Uno/Term/Object Binary Interface|OBI]] and the "purposes" are expressed in the descriptor of the objects managing [[Uno/Spec/Environment|environment]], e.g. the [[Uno/Spec/Environment|environment]] described by <code>"gcc3:unsafe"</code> manages objects with a GCC3 C++ [[Uno/Term/Object Binary Interface|OBI]] (if named properly, it would have been called "g++3" or "gpp3"), which are [[Uno/Term/Thread Unsafe|thread-unsafe]].
  
The [[Uno/Spec/Threading Model|Uno threading model]] brings [[Uno/Spec/Thread Affinity Bridge|thread-affine purpose environments]] and [[Uno/Spec/Thread Unsafety Bridge|thread-unsafe purpose environments]]. Objects not belonging to one of these two [[Uno/Spec/Purpose Environment|purpose environments]] are assumed to be [[Uno/Term/Thread Safe|thread-safe]].  
+
The [[Uno/Spec/Threading-Model|Uno threading-model]] introduces [[Uno/Spec/Thread Affinity Bridge|thread-affine purpose environments]] and [[Uno/Spec/Thread Unsafety Bridge|thread-unsafe purpose environments]]. Objects not belonging to one of these two [[Uno/Spec/Purpose Environment|purpose environments]] are assumed to be [[Uno/Term/Thread Safe|thread-safe]].  
  
 
Examples:
 
Examples:
* <code>"gcc3:unsafe"</code> - Environment for managing objects with a GCC3 C++ ABI, which are [[Uno/Term/Thread Unsafe|thread-unsafe]].
+
* <code>"gcc3:unsafe"</code> - [[Uno/Spec/Environment|Environment]] for managing objects with a GCC3 C++ [[Uno/Term/Object Binary Interface|OBI]], which are [[Uno/Term/Thread Unsafe|thread-unsafe]].
* <code>"java"</code> - Environment for managing Java JNI objects, without any further characteristics, therefor the managed objects have to be [[Uno/Term/Thread Safe|thread-safe]].
+
* <code>"java"</code> - [[Uno/Spec/Environment|Environment]] for managing Java JNI objects, no further characteristics (AKA purposes) have been specified, therefore the managed objects have to be [[Uno/Term/Thread Safe|thread-safe]].
* <code>"java:affine"</code> - Environment for managing Java JNI objects which are [[Uno/Term/Thread Affine|thread-affine]].
+
* <code>"java:affine"</code> - [[Uno/Spec/Environment|Environment]] for managing Java JNI objects which are [[Uno/Term/Thread Affine|thread-affine]].
  
====Thread-Unsafe====
+
===[[Uno/Term/Thread Safe|Thread-Safe]]===
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 [[Uno/Spec/Environment|environment]] with neither <code>":unsafe"</code> nor <code>":affine"</code> in its description is a [[Uno/Term/Thread Safe|thread-safe]] environment. Objects managed by such an environment may very well be called directly by concurrent threads. Examples for [[Uno/Term/Thread Safe|thread-safe]] environments are <code>"gcc3"</code> or <code>"java"</code>, and also <code>"gcc3:debug"</code> or <code>"uno:debug"</code>.
  
=====C++ Example - Entering a thread-unsafe environment=====
+
===[[Uno/Term/Thread Unsafe|Thread-Unsafe]]===
 +
Any environment with an <code>":unsafe"</code> 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 - Activating a [[Uno/Term/Thread Unsafe|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]
+
<source lang="cpp">
 
...
 
...
 
{
 
{
 
   // Enter the "gcc3:unsafe" environment
 
   // Enter the "gcc3:unsafe" environment
   cppu::EnvGuard unsafeGuard(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:unsafe"))));
+
   cppu::EnvGuard unsafeGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:unsafe"))));
 
   // Now we can safely directly call on any object belonging to this environment,
 
   // Now we can safely directly call on any object belonging to this environment,
 
   // no second thread can enter this environment in parallel
 
   // no second thread can enter this environment in parallel
 
   pObj->doSomething();
 
   pObj->doSomething();
  
   // We implicity leave the "gcc3:unsafe" environment
+
   // We implicity leave the "gcc3:unsafe" environment by destruction of the unsafeGuard
 
}
 
}
 
...
 
...
</code>
+
</source>
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 <code>"<OBI>:unsafe"</code> environment in one particular process.
  
====Thread-Affine====
+
===[[Uno/Term/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 [[Uno/Spec/Environment|environment]] with an <code>":affine"</code> in its description is a [[Uno/Term/Thread Affine|thread-affine]] environment. Objects managed by such an [[Uno/Spec/Environment|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 [[Uno/Term/Thread Affine|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 already associated thread leaves the [[Uno/Spec/Environment|environment]]. An associated thread may only leave a [[Uno/Term/Thread Affine|thread-affine]] environment, in case no object is more managed (e.g. the last managed object has been removed). Finally, the entering thread becomes the associated thread of the [[Uno/Term/Thread Affine|thread-affine]] environment. All invocations of objects of this [[Uno/Term/Thread Affine|thread-affine]] environment get dispatched into the associated thread.
  
=====C++ Example - Entering a thread-affine environment=====
+
In contrast, "invoking" a [[Uno/Term/Thread Affine|thread-affine]] environment creates a new, dedicated and hidden thread to be associated with it, in case no thread has been associated with it yet, all invocations of objects or functions are then dispatched to this (new) thread. This new thread gets terminated when the last managed objects becomes removed.
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.
+
  
<code>[cpp]
+
====C++ Example - Entering a [[Uno/Term/Thread Affine|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 [[Uno/Term/Thread Affine|thread-affine]] environment, the d'tor of the <code>affineGuard</code> will block as long as objects are managed by this [[Uno/Spec/Environment|environment]], basically ensuring that the objects are still reachable.
 +
 
 +
<source lang="cpp">
 
class MyUnoObject ...;
 
class MyUnoObject ...;
  
 
...
 
...
 
{
 
{
   cppu::EnvGuard affineGuard(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
+
   cppu::EnvGuard affineGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
 
    
 
    
 +
  uno::Reference<XMultiServiceFactory> smgr(...);
 +
 
   smgr->createInstanceWithArguments(new MyUnoObject());
 
   smgr->createInstanceWithArguments(new MyUnoObject());
  
   // the implicit "leave" call blocks, until all objects managed by "gcc3:affine" are released.
+
   // The implicit leave of the "gcc3:affine" blocks, until all managed objects (MyUnoObjects) are removed.
 
}
 
}
 
...
 
...
</code>
+
</source>
  
=====C++ Example - Invoking a thread-affine environment=====
+
====C++ Example - Invoking a [[Uno/Term/Thread Affine|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.
+
This example shows, how to correctly invoke a [[Uno/Term/Thread Affine|thread-affine]] environment, as always, all objects need to be managed properly by their managing [[Uno/Spec/Environment|environments]].
<code>[cpp]
+
<source lang="cpp">
 
class MyUnoObject ...;
 
class MyUnoObject ...;
  
Line 77: Line 236:
 
...
 
...
 
{
 
{
   uno::Environment affineEnv(Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
+
   uno::Environment affineEnv(uno::Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
  
   Mapping curr2affine(uno::getCurrentEnvironment(), affineEnv);
+
   uno::Mapping curr2affine(uno::Environment::getCurrent(), affineEnv);
  
 
   void * affineSmgr = curr2affine.mapInterface(smgr, typeof(smgr));
 
   void * affineSmgr = curr2affine.mapInterface(smgr, typeof(smgr));
Line 86: Line 245:
 
}
 
}
 
...
 
...
</code>
+
</source>
  
====Thread-Safe====
+
==Helpers==
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>.
+
The helpers ease the mapping of objects from particular purpose [[Uno/Spec/Environment|environment]] to another. Where [[Uno/Spec/Mapping|mappings]] may be independently used to map any object to anywhere, the helpers take into account the current context.
  
===Helpers===
+
===Map 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 [[Uno/Cpp/Spec/Shield Helpers|specification for the shield helpers]] for more details.
+
===Shield Helpers===
 +
====[[Uno/Cpp/Spec/Shield Helpers|C++ Shield Helpers]]====
 +
The "shield" helpers basically allow to shorten the mapping of an object
 +
* from the current (typically [[Uno/Term/Thread Unsafe|thread-unsafe]] or [[Uno/Term/Thread Affine|thread-affine]]) C++ environment, to the [[Uno/Term/Thread Safe|thread-safe]] C++ environment,
 +
* from the [[Uno/Term/Thread Safe|thread-safe]] C++ environment to the current (typically [[Uno/Term/Thread Unsafe|thread-unsafe]] or [[Uno/Term/Thread Affine|thread-affine]]) C++ environment.
  
======C++ Example - Map Object to Thread-Safe======
+
Please have a look a the [[Uno/Cpp/Spec/Shield Helpers|shield helpers specification]] for more details.
 +
 
 +
=====C++ Example - Map Object to [[Uno/Term/Thread Safe|Thread-Safe]]=====
 
Do the mapping by hand:
 
Do the mapping by hand:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::XInterface * pUnsafe_Object ...;
 
uno::XInterface * pUnsafe_Object ...;
Line 110: Line 271:
 
                                     curr2safe.mapInterface(
 
                                     curr2safe.mapInterface(
 
                                       pObject,  
 
                                       pObject,  
                                       getCppuType((cssu::Reference<XInterface> *)NULL)
+
                                       getCppuType((uno::Reference<uno::XInterface> *)NULL)
 
                                     )
 
                                     )
 
                                 );
 
                                 );
 
...
 
...
</code>
+
</source>
 
Can be simply replaced with:
 
Can be simply replaced with:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::XInterface * pUnsafe_Object ...;
 
uno::XInterface * pUnsafe_Object ...;
 
uno::XInterface * pSafe_Object = cppu::shield(pUnsafe_Object);
 
uno::XInterface * pSafe_Object = cppu::shield(pUnsafe_Object);
 
...
 
...
</code>
+
</source>
  
======C++ Example - Map Object from Thread-Safe======
+
=====C++ Example - Map Object from [[Uno/Term/Thread Safe|Thread-Safe]]=====
 
Do the mapping by hand:
 
Do the mapping by hand:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::XInterface * pSafe_Object ...;
 
uno::XInterface * pSafe_Object ...;
Line 134: Line 295:
 
                                     safe2curr.mapInterface(
 
                                     safe2curr.mapInterface(
 
                                       pObject,  
 
                                       pObject,  
                                       getCppuType((cssu::Reference<uno::XInterface> *)NULL)
+
                                       getCppuType((uno::Reference<uno::XInterface> *)NULL)
 
                                     )
 
                                     )
 
                                   );
 
                                   );
 
...
 
...
</code>
+
</source>
 
Can be simply replaced with:
 
Can be simply replaced with:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::XInterface * pSafe_Object ...;
 
uno::XInterface * pSafe_Object ...;
 
uno::XInterface * pUnsafe_Object = cppu::unshield(pSafe_Object);
 
uno::XInterface * pUnsafe_Object = cppu::unshield(pSafe_Object);
 
...
 
...
</code>
+
</source>
  
======C++ Example - Map <code>uno::Any</code> to Thread-Safe======
+
=====C++ Example - Map <code>uno::Any</code> to [[Uno/Term/Thread Safe|Thread-Safe]]=====
 
Do the mapping by hand:
 
Do the mapping by hand:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::Any unsafeAny = ...
 
uno::Any unsafeAny = ...
Line 163: Line 324:
 
                                 curr2safe.get());
 
                                 curr2safe.get());
 
...
 
...
</code>
+
</source>
 
Can be simply replaced with:
 
Can be simply replaced with:
<code>[cpp]
+
<source lang="cpp">]
 
...
 
...
 
uno::Any unsafeAny = ...
 
uno::Any unsafeAny = ...
 
uno::Any safeAny(cppu::shieldAny(unsafeAny));
 
uno::Any safeAny(cppu::shieldAny(unsafeAny));
 
...
 
...
</code>
+
</source>
  
======C++ Example - Map <code>uno::Any</code> from Thread-Safe======
+
=====C++ Example - Map <code>uno::Any</code> from [[Uno/Term/Thread Safe|Thread-Safe]]=====
 
Do the mapping by hand:
 
Do the mapping by hand:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::Any safeAny = ...
 
uno::Any safeAny = ...
Line 188: Line 349:
 
                                 safe2curr.get());
 
                                 safe2curr.get());
 
...
 
...
</code>
+
</source>
 
Can be simply replaced with:
 
Can be simply replaced with:
<code>[cpp]
+
<source lang="cpp">
 
...
 
...
 
uno::Any safeAny = ...
 
uno::Any safeAny = ...
 
uno::Any unsafeAny(cppu::unshieldAny(safeAny));
 
uno::Any unsafeAny(cppu::unshieldAny(safeAny));
 
...
 
...
</code>
+
</source>
  
===Objects===
+
==Threads==
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
+
Thinking about threads, thread related environments and [[Uno/Spec/Object|Uno objects]], we roughly can identify the following types,
* [[Uno/Term/Thread Unsafe|thread-unsafe]], or
+
* asynchronous threads, which run in the [[Uno/Term/Thread Safe|thread-safe]] environment,
* [[Uno/Term/Thread Safe|thread-safe]], or
+
* synchronous threads, which run in a [[Uno/Term/Thread Unsafe|thread-unsafe]] or [[Uno/Term/Thread Affine|thread-affine]] environment,
* [[Uno/Term/Thread Affine|thread-affine]].
+
* hidden threads, which run behind an objects implementation only.
 
+
====Architecture====
+
=====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]].
+
 
+
=====Thread-Safe=====
+
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
+
* you want to avoid any overhead associated with leaving synchronization to the [[Uno/Spec/Runtime|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 [http://util.openoffice.org/source/browse/util/io/source/acceptor/ 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 [[Uno/Spec/Environment|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 [[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=====
+
[[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====
+
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 <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]
+
extern "C" void SAL_CALL component_getImplementationEnvironment(
+
  sal_Char        const ** ppEnvTypeName,
+
  uno_Environment      ** ppEnv
+
)
+
{
+
  *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME ":unsafe";
+
}
+
</code>
+
 
+
======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:
+
<code>[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);
+
}
+
</code>
+
 
+
=====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 an appropriate 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.
+
 
+
Callee:
+
<code>[cpp]
+
// this function is environment specialized on "cpp<purpose>*"
+
uno::Reference<uno::XInterface> returnMyUnsafeObject(void) {
+
  uno:Reference<uno::XInterface>  currThreading_Obj = NULL;
+
  {
+
    uno::Environment unsafeEnv(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:unsafe")));
+
 
+
    uno::XInterface * pUnsafeEnv_Obj = NULL;
+
    {
+
      cppu::EnvGuard unsafeGuard(unsafeEnv);
+
 
+
      pUnsafeEnv_Obj = new MyUnsafeObject();
+
    }
+
 
+
    Mapping unsafe2curr(unsafeEnv, uno::getCurrentEnv());
+
    currThreading_Obj.set(unsafe2curr.mapInterface(pUnsafeEnv_Obj, typeof(XInterface)), SAL_NO_ACQUIRE);
+
    unsafeEnv.get()->pExtEnv->releaseInterface(pUnsafeEnv_Obj);
+
  }
+
 
+
  return currThreading_Obj;
+
}
+
</code>
+
 
+
Caller:
+
<code>[cpp]
+
...
+
{
+
  cppu::EnvGuard gcc3Debug_Guard(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:debug")));
+
 
+
  uno::Referenc obj(returnMyUnsafeObject());
+
}
+
...
+
</code>
+
 
+
======C++ Example - Function appropriately mapping parameters======
+
In the following example, the called function gets a parameter, which needs to be mapped appropriately to the <code>"gcc3: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 have activated the appropriate environment, as the <code>uno::Reference</code> is only partly (namely ABI) specialized.
+
 
+
Callee:
+
<code>[cpp]
+
// this function is environment specialized on "cpp<purpose>*"
+
void setUnsafeObject(uno::Reference<...> const & rObj) {
+
  uno::Environment unsafeEnv(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:unsafe")));
+
 
+
  Mapping curr2unsafe(uno::getCurrentEnv(), unsafeEnv);
+
 
+
  {
+
    cppu::EnvGuard unsafeGuard(unsafeEnv);
+
    Reference<type> unsafeEnv_Obj.set(curr2unsafe.mapInterface(rObj.get(), typeof(rObj)),
+
                                      SAL_NO_ACQUIRE);
+
 
+
    // MyUnsafeObj has a "gcc3" C++ ABI and is thread-unsafe
+
    pUnsafeEnv_Obj->set(new MyUnsafeObject());
+
  }
+
}
+
</code>
+
 
+
Caller:
+
<code>[cpp]
+
...
+
{
+
  cppu::EnvGuard gcc3Debug_Guard(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:debug")));
+
 
+
  uno::Reference<...> obj(...);
+
  setUnsafeObj(obj);
+
}
+
...
+
</code>
+
 
+
===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.
 
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 to the same particular object. In case a called object is not [[Uno/Term/Thread Safe|thread-safe]] (e.g. [[Uno/Term/Thread Unsafe|thread-unsafe]] or [[Uno/Term/Thread Affine|thread-affine]]), the appropriate [[Uno/Spec/Environment|environment]] becomes activated respectively deactivated implicitly before and 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 [[Uno/Term/Thread Unsafe|thread-unsafe]] or [[Uno/Term/Thread Affine|thread-affine]] objects. Before actually invoking any object, the thread does activate the (respectively any) managing [[Uno/Spec/Environment|environment]]. The calls are therefor not competing with any other thread and the call sequence is atomic. After a sequence of calls, the thread deactivates the managing [[Uno/Spec/Environment|environment]] again.
  
====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 [[Uno/Spec/Environment|environment]] explicitly, just run in the [[Uno/Term/Thread Safe|thread-safe]] environment. Only implicitly activate other [[Uno/Spec/Environment|environments]] when invoking mapped objects (e.g. [[Uno/Term/Thread Unsafe|thread-unsafe]] object).
  
<code>[cpp]
+
<source lang="cpp">
 
class MyThread : public Thread  
 
class MyThread : public Thread  
 
{
 
{
Line 368: Line 391:
  
 
public:
 
public:
   MyThread(uno::Reference<XInterface> const & xInterface)
+
   MyThread(uno::Reference<...> const & object)
     : m_xInterface(cppu::shield(xInterface), SAL_NO_ACQUIRE)
+
     : m_safe_obj(cppu::shield(object), SAL_NO_ACQUIRE)
 
   {}
 
   {}
 
};
 
};
</code>
+
</source>
  
=====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 an [[Uno/Spec/Environment|environment]] and do all calls while being in it. Obviously, releasing the objects also needs to be done in the environment.
<code>[cpp]
+
<source lang="cpp">
 
class MyThread : public Thread  
 
class MyThread : public Thread  
 
{
 
{
Line 382: Line 405:
 
   uno::Reference<...> m_unsafe_obj;
 
   uno::Reference<...> m_unsafe_obj;
  
   static void s_doSomething(va_list param)
+
   static void s_clear(va_list param)
 
   {
 
   {
 
     MyThread * pMyThread = va_arg(param, MyThread *);
 
     MyThread * pMyThread = va_arg(param, MyThread *);
Line 399: Line 422:
  
 
public:
 
public:
   MyThread(uno::Reference<XInterface> const & xInterface);
+
   MyThread(uno::Reference<...> const & object);
     : m_xInterface(xInterface), m_refEnv(uno::getCurrentEnvironment());
+
     : m_unsafe_obj(object), m_refEnv(uno::Environment::getCurrent());
 
   {}
 
   {}
  
Line 410: Line 433:
 
   }
 
   }
  
   void doSomething()
+
   virtual void SAL_CALL run()
 
   {
 
   {
 
     m_refEnv.invoke(s_doSomething, this);
 
     m_refEnv.invoke(s_doSomething, this);
 
   }
 
   }
 
};
 
};
</code>
+
</source>
  
 
==Specifications==
 
==Specifications==
 
The relevant specifications can be found here:
 
The relevant specifications can be found here:
* [[Uno/Spec/Threading Model]]
+
* [[Uno/Spec/Threading-Model]]
** [[Uno/Binary/Spec/Threading Model]]
+
** [[Uno/Binary/Spec/Threading-Model]]
** [[Uno/Cpp/Spec/Threading Model]]
+
** [[Uno/Cpp/Spec/Threading-Model]]
  
 
In particular:
 
In particular:
Line 432: Line 455:
 
** [[Uno/Binary/Spec/Thread Unsafety Bridge]]
 
** [[Uno/Binary/Spec/Thread Unsafety Bridge]]
 
* [[Uno/Spec/Purpose Environment]]
 
* [[Uno/Spec/Purpose Environment]]
** [[Uno/Binary/Spec/Purpose Environments]]
+
** [[Uno/Binary/Spec/Environment Descriptor]]
** [[Uno/Cpp/Spec/Purpose Environments]]
+
** [[Uno/Cpp/Spec/Environment Descriptor]]
 
* [[Uno/Spec/Cascaded Mapping]]
 
* [[Uno/Spec/Cascaded Mapping]]
 
** [[Uno/Binary/Spec/Cascaded Mapping]]
 
** [[Uno/Binary/Spec/Cascaded Mapping]]
Line 443: Line 466:
  
 
==See also==
 
==See also==
* Using C++ with OOo SDK : [[Using_Cpp_with_the_OOo_SDK | Main Page]]
+
* Using C++ with OOo SDK : [[Using_Cpp_with_the_OOo_SDK|Main Page]]
* [[SDKCppLanguage#Threads | Threads]]
+
* [[SDKCppLanguage#Threads|Threads]]
  
  
[[Category:Uno:Article]]
+
[[Category:Uno]]
 +
[[Category:Cpp]]
 +
[[Category:Article]]
 +
[[Category:Tutorial]]
 +
[[Category:Multi-Threading]]

Latest revision as of 17:31, 23 February 2008

Note: The technology described in this article depends on the presence of the extended Binary Uno threading-model, which has been integrated into URE 1.3 (SRC680_m212).

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

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

  • the dedicated, thread related environments,
  • how to use these environments when creating particular implementations,
  • and certainly, how to use threads wrt. Uno objects.

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

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

Purpose

Thread-Unsafe

Thread unsafe is the choice for most cases. Actually leaving proper synchronization of method calls to the Uno 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 Uno runtime.

One case, where your object must allow the parallel execution of methods is, when you want to be able to abort a running invocation of one of its methods. 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 Uno 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 independently.

Thread-Affine

Thread-affine objects are rare. In OOo they are needed to encapsulate the Win32 respectively the OLE/COM thread-affinity. See Make Vcl Thread-Transparent for details.

Implementation

Every 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. This 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 of a component does return the single managing environment for all objects provided by this component. The implementation of this function for thread-unsafe objects may look like this:

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:

#include "cppu/EnvDcp.hxx"
 
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 always do return appropriate objects, the implementations of the API are only OBI specialized and dynamically map the return or parameter objects according to the callers (purpose) environment.

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 a thread-safe object, while the objects implementation itself is thread-unsafe. For this function to work properly, the client must have left any thread-unsafe environment.

Callee:

// 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.
  assert(uno::Environment::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.
    uno::Reference<uno::XInterface> unsafeEnv_Obj(new MyUnsafeObject());
 
    // We may do some invocations on "unsafeEnv_Obj" while being in the "unsafe" environment.
    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 fine here.
  return result_Obj;
}

Caller:

...
{
  // We just 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:

// 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.
  assert(uno::Environment::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.
  uno::Reference<...> unsafeEnv_Obj.set(cppu::unshield(rObj), SAL_NO_ACQUIRE);
 
  // MyUnsafeObj has a C++ OBI and is thread-unsafe
  unsafeEnv_Obj->set(new MyUnsafeObject());
}

Caller:

...
{
  // We leave all "purpose" environments here, as "setUnsafeObject" accepts
  // "c++" (thread-safe) objects only.
  cppu::AntiEnvGuard antiGuard;
 
  uno::Reference<...> obj(...);
  setUnsafeObj(obj);
}
...

Environments

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

The Uno threading-model introduces 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:

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".

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 - Activating a thread-unsafe Environment

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

...
{
  // Enter the "gcc3:unsafe" environment
  cppu::EnvGuard unsafeGuard(uno::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 by destruction of the unsafeGuard
}
...

Basically, only one thread at a time can have activated any "<OBI>:unsafe" environment in one particular 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 already associated thread leaves the environment. An associated thread may only leave a thread-affine environment, in case no object is more managed (e.g. the last managed object has been removed). Finally, the entering thread becomes the associated thread of the thread-affine environment. All invocations of objects of this thread-affine environment get dispatched into the associated thread.

In contrast, "invoking" a thread-affine environment creates a new, dedicated and hidden thread to be associated with it, in case no thread has been associated with it yet, all invocations of objects or functions are then dispatched to this (new) thread. This new thread gets terminated when the last managed objects becomes removed.

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.

class MyUnoObject ...;
 
...
{
  cppu::EnvGuard affineGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
 
  uno::Reference<XMultiServiceFactory> smgr(...);
 
  smgr->createInstanceWithArguments(new MyUnoObject());
 
  // The implicit leave of the "gcc3:affine" blocks, until all managed objects (MyUnoObjects) are removed.
}
...

C++ Example - Invoking a thread-affine Environment

This example shows, how to correctly invoke a thread-affine environment, as always, all objects need to be managed properly by their managing environments.

class MyUnoObject ...;
 
void doSomething(va_list param)
{
  XMultiServiceFactory * pSmgr = va_arg(param, XMultiServiceFactory *);
  pSmgr->createInstanceWithArguments(new MyUnoObject());
}
 
...
{
  uno::Environment affineEnv(uno::Environment(rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("gcc3:affine"))));
 
  uno::Mapping curr2affine(uno::Environment::getCurrent(), affineEnv);
 
  void * affineSmgr = curr2affine.mapInterface(smgr, typeof(smgr));
  affineEnv.invoke(s_doSomething, affineSmgr);
  affineEnv.get()->pExtEnv->releaseInterface(affineSmgr);
}
...

Helpers

The helpers ease the mapping of objects from particular purpose environment to another. Where mappings may be independently used to map any object to anywhere, the helpers take into account the current context.

Map Helpers

Shield Helpers

C++ Shield Helpers

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

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

C++ Example - Map Object to Thread-Safe

Do the mapping by hand:

...
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((uno::Reference<uno::XInterface> *)NULL)
                                    )
                                 );
...

Can be simply replaced with:

...
uno::XInterface * pUnsafe_Object ...;
uno::XInterface * pSafe_Object = cppu::shield(pUnsafe_Object);
...
C++ Example - Map Object from Thread-Safe

Do the mapping by hand:

...
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((uno::Reference<uno::XInterface> *)NULL)
                                     )
                                   );
...

Can be simply replaced with:

...
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:

...
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:

]
...
uno::Any unsafeAny = ...
uno::Any safeAny(cppu::shieldAny(unsafeAny));
...
C++ Example - Map uno::Any from Thread-Safe

Do the mapping by hand:

...
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:

...
uno::Any safeAny = ...
uno::Any unsafeAny(cppu::unshieldAny(safeAny));
...

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 behind 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 to the same particular object. In case a called object is not thread-safe (e.g. thread-unsafe or thread-affine), the appropriate environment becomes activated respectively deactivated implicitly before and after the call.

Synchronous

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

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 invoking mapped objects (e.g. thread-unsafe object).

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<...> const & object)
    : m_safe_obj(cppu::shield(object), SAL_NO_ACQUIRE)
  {}
};

Synchronous Thread

Just enter an environment and do all calls while being in it. Obviously, releasing the objects also needs to be done in the environment.

class MyThread : public Thread 
{
  uno::Environment    m_refEnv;
  uno::Reference<...> m_unsafe_obj;
 
  static void s_clear(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<...> const & object);
    : m_unsafe_obj(object), m_refEnv(uno::Environment::getCurrent());
  {}
 
  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);
  }
 
  virtual void SAL_CALL run()
  {
    m_refEnv.invoke(s_doSomething, this);
  }
};

Specifications

The relevant specifications can be found here:

In particular:

See also

Personal tools