Apartment Model and Threading Issues

Most existing COM objects are not thread-safe. That is, clients are required to make all calls to the COM object from a single thread. In addition, this thread is required to process Window messages on a regular basis so that other threads can marshal calls to objects on that thread and so that system message broadcasts do not get blocked. (A thread that processes Window messages regularly is said to have a message pump.)

Furthermore, some COM objects are not even apartment-aware. These objects are not only restricted to a single thread, but are restricted to a specific thread known as the main apartment thread. The first thread that calls CoInitialize becomes the main apartment thread for the process.

The following sections describe how the Microsoft VM instantiates COM objects and creates marshaling proxies while hiding the details from the Java programmer.

Instantiating New COM Objects

When a Java class representing a COM object is instantiated using new, the VM for Java obtains the COM object's threading model from the registry. What happens next depends on which threading model is in effect:

If the threading model is Both or Free, the object is assumed to be thread-safe and is instantiated on the calling thread. Any method call on this object will translate directly to a method call on the underlying COM object on the calling thread.

If the threading model is Single, the Microsoft VM automatically marshals to the process main apartment thread to create the object. Furthermore, it marshals all method calls on this object back to the main apartment thread. This represents additional overhead, but this is required for non–thread-safe objects.

If the threading model is Apartment, the Microsoft VM marshals the object creation and method calls in similar fashion. The choice of thread is determined as follows. If the creating thread is considered apartment-hostable, the object is created on that thread. Otherwise, the object is created on a special apartment thread created automatically by the Microsoft VM. All objects created in this fashion share one special apartment thread. The Microsoft VM does not create a new thread for every object.

How Marshaling Works

Java proxies are not only created when a COM object is instantiated using new. They are also created whenever a Java method is passed an object from COM and whenever Java receives an object from a COM method through a return value. In both cases (when a Java method is passed a COM object and when Java receives a COM object via a return value), there is no registry entry that provides the threading model of the object. The Microsoft VM for Java must be told explicitly whether the interface can be assumed to be thread-safe. If the interface is not thread-safe, the Microsoft VM must marshal all calls to the thread on which the interface was received. The jactivex tool adopts a conservative policy and marks all interface parameters as requiring marshaling.

Even when the interface parameter is marked as requiring marshaling, the Microsoft VM will produce a non-marshaling proxy if the COM object indicates that it is thread-safe by aggregating the free-threaded marshaler (using CoCreateFreeThreadedMarshaler).

The VM can only create a marshaling proxy on a thread that is apartment-hostable. If a call is made to a Java proxy, which is itself hosted on an apartment thread, proxies for the parameters to that call are made on that apartment thread. Hence, this requirement is automatically satisfied. If the thread is not apartment-hostable, the proxy creation will fail with a ClassCastException.