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

Revision as of 13:14, 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 Object Binary Interface (OBI), the object may have one or multiple "purposes" associated with it. The OBI and the "purposes" are expressed in 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 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++ OBI, 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 "<OBI>: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))));

                                   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());

                                    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))));

                                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))));

                                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

• thread-unsafe, or
• thread-safe, or
• thread-affine.

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 OBI) 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 OBI 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 OBI) 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++ OBI 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

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

 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();
 }

 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:

• Uno/Spec/Threading Model
  • Uno/Binary/Spec/Threading Model
  • Uno/Cpp/Spec/Threading Model

In particular:

• Uno/Spec/Environment Stack
  • Uno/Binary/Spec/Environment Stack
  • Uno/Cpp/Spec/Environment Stack
• Uno/Spec/Thread Affinity Bridge
  • Uno/Binary/Spec/Thread Affinity Bridge
• Uno/Spec/Thread Unsafety Bridge
  • Uno/Binary/Spec/Thread Unsafety Bridge
• Uno/Spec/Purpose Environment
  • Uno/Binary/Spec/Purpose Environments
  • Uno/Cpp/Spec/Purpose Environments
• Uno/Spec/Cascaded Mapping
  • Uno/Binary/Spec/Cascaded Mapping
• Uno/Spec/Environment Substitution
• (Uno/Spec/Implementation Environment)
  • (Uno/Binary/Spec/Implementation Environment)
  • (Uno/Cpp/Spec/Implementation Environment)
• Uno/Cpp/Spec/Environment Guard

See also

• Using C++ with OOo SDK : Main Page
• Threads