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

Revision as of 10:05, 15 June 2006

Preface

The technologie described in this article depends on the presence of the Uno/Effort/Creating the Uno Threading Framework.

Multi Threading Programming

UNO is inherently multi threaded. Every instance of a UNO component may be accessed by multiple threads concurrently. The UNO threading framework provides support for simplifying multi thread programming.

Every UNO reference points to an object with particular characteristics. Among implementing a concrete interface, the object may belong to a particular Purpose Environment. The UNO Threading Framework introduces the Thread Affine Purpose Environment and Thread Unsafe Purpose Environments. Objects not belonging to one of these two Purpose Environments are assumed to be Thread Safe.

Implementing Objects

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

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 want to implement your object Thread Safe. Either

your component should or must allow the concurrent execution of some of its methods, or
your component wants to avoid the overhead associated with leaving synchronization to the Runtime.

One case, where your component must allow the concurrent 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 entered by multiple threads concurrently.

Thread Affine

Thread Affine objects are rare. In OOo they are needed to encapsulate the Win32 thread affinity.

Thread Free

Thread Free objects may be used in any threading environment. They certainly need to respect particular environment related constraints.

Note: Unfortunately, no type safe specialized purpose references are yet available for any UNO language binding. So, this is planned. Currently, the only possible way to detect the purpose of a reference is at runtime, via the getCurrentEnvironment Runtime function.

Note: The UNO Runtime provides APIs for implementing any whished scenario. Including objects shared between different Purpose Environments or the instantiation of a Thread Safe component in a Thread Unsafe Environment. These mechanisms are in place to implement the Threading Framework itself, and to allow the programmer to gain full control, if needed.

Using Threads

You may create threads in your implementation. Depending on the selected threading architecture, these threads may are allowed to be visible from the outside or not. If your implementation is

Thread Unsafe, than it must be Thread Transparent, if it is
Thread Affine, than is must be Thread Transparent as well, if it is
Thread Safe, it may create visible threads and be Uno/Term/Thread Aware as needed,
Thread Free, it may behave according to the surrounding environment.

Obviously, invisible threads can be used and created anytime anyway. Invisible threads do not harm Thread Transparency.

Implementation Types

Depending on the type of the planned implementation, which either is a

component, or a
library, or an
application,

care of the "purpose" characteristic of the involved objects needs to be taken.

Note: It is planned, to support the selection of an Implementation Environment (determining the implementations Purpose Environment) by a macro or an include. Some experiments have been done, so no final decisions have been made yet.

Components

C++

Thread Specialized components directly return their ABI plus their thread related specialisation. The implementation of the component_getImplementationEnvironment function for a Thread Unsafe component needs to reflect this unsafeness by providing it together with the ABI, e.g.:

extern "C" void SAL_CALL component_getImplementationEnvironment(sal_Char        const ** ppEnvTypeName, 
								uno_Environment       ** ppEnv)
{
	*ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME ":unsafe";
}

A Thread Free component providing objects for all thread related environment needs to implement the component_getImplementationEnvironmentExt function, e.g.:

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

Implementing this function, the Component may very well differentiate the threading environments depending on the desired implementation names.

Libraries

Libraries providing functions dealing with UNO objects may be implemented according to the above list. Currently, it is only possible to different between

Thread Free, meaning that the library can deal with any kind of objects, and
Thread Specialized (Uno/Term/Thread Unsafe, Uno/Term/Thread Safe, Uno/Term/Thread Affine), meaning that the library can deal with one particular purpose type of objects only.

Thread Free and Thread Specialized functions may be mixed, depending on the libraries purpose, this may or may not be good style.

C++

The API of Uno/Term/Thread Free libraries should reflect the "freeness" by using the cppu::EnvAwareReference in its API definition, e.g.:

// Declaration
cppu::EnvAwareReference<XSingleServiceFactory> get_a_factory(void);

For compatibility reasons, standard Uno references (com::sun::star::uno::Reference) may be used, doing a runtime check for the thread type of the passed or desired objects, e.g.:

// Declaration
uno::Reference<XSingleServiceFactory> get_a_factory(void);

// Implementation
uno::Reference<XSingleServiceFactory> get_a_factory(void)
{
  cppu::EnvAwareReference<XSingleServiceFactory> rFactory(new MyThreadUnsafeFactory());

  {  
    cppu::EnvGuard envGuard(uno::Environment(rtl::OUString(RTL_CONSTASCII_PARAM("uno:unsafe"))));
    rFactory.set(new MyThreadUnsafeFactory());
  }

  return rFactory;
}

The cppuhelper library dynamically checks the current environment, and returns matching references, e.g. guaranteeing that Thread Safe and Thread Unsafe objects do not get mixed.

Applications

Application code implemented other than in the Thread Safe environment needs to explicitly enter the wished Purpose Environment before calling any UNO aware library. UNO aware libraries may than provide matching objects, dependent on the implementation, again ensuring that objects with different "purposes" do not get mixed.

Note: The planned introduction of Implementation Environments is going to be usable by the application programmer as well. It basically removes the necessity to explicitly enter a particular Purpose Environment.

@@ Line 81: / Line 81: @@
 }
 </pre>
+Implementing this function, the Component may very well differentiate the threading environments depending on the desired implementation names.
 ==== Libraries ====