Uno/Article/Multi-Thread Programming

From Apache OpenOffice Wiki
< Uno
Revision as of 09:59, 9 August 2006 by Kr (Talk | contribs)

Jump to: navigation, search

Preface

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

Multi-Thread Programming

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 terminates. The associated thread terminates the moment, the last managed object is 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, 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".

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
  • your object wants to avoid the 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 the 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 simultanesously 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:

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:

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 specialization of a function.

C++ Example - Function always returning an appropriate object

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

callee.cxx:
  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;
  }

caller.cxx:
  ...
  {
    cppu::EnvGuard gcc3Debug_Guard(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:debug")));

    uno::Referenc obj(returnMyUnsafeObject());
  }
  ...
C++ Example - Function appropriately mapping parameters

In the following example, the called function gets a parameter, which needs to be mapped appropriately to the "gcc3: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 have activated the appropriate environment, as the uno::Reference is only partly (namely ABI) specialized.

callee.cxx:
  void setUnsafeObject(uno::Reference<...> const & rObj) {
    uno::Environment unsafeEnv(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:unsafe")));

    Mapping curr2unsafe(uno::getCurrentEnv(), unsafeEnv);
    <type> * pUnsafeEnv_Obj = curr2unsafe.mapInterface(rObj.get(), typeof(rObj));

    {
      cppu::EnvGuard unsafeGuard(unsafeEnv);
      pUnsafeEnv_Obj->set(new MyUnsafeObject()); // MyUnsafeObj has a "gcc3" C++ ABI and is thread-unsafe
    }

    unsafeEnv.get()->pExtEnv->releaseInterface(pUnsafeEnv_Obj);
  }

caller.cxx:
  ...
  {
    cppu::EnvGuard gcc3Debug_Guard(rtl::OUString(RTL_CONSTASCII_PARAM("gcc3:debug")));

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

Threads

Categories

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

...
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<T> *)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((cssu::Reference<T> *)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));
...

C++ Examples

Asynchronous Thread

Do not enter the environment explicitly, but only implicitly when calling methods on mapped objects (assuming the objects have been implemented in the target environment).

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.

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

Personal tools