#89: Description of Instancing and Threading Models in COM-servers

When you create a new COM object, you must define the Instancing and Threading Model, which will be used in your COM object. For example, when you use the Automation Object Wizard (select File|New from main menu, click the ActiveX tab and select Automation Object Wizard item) you must select a desired values of Instancing/Threading Model from comboboxes.

In this article I'll include a short description for each value.

1. Instancing refers to how many instances of the COM object are created for a request of client. You can select a one option from three available items: Single Instance, Multiple Instance and Internal.

a) Single Instance - allows only a single COM interface for each executable. So creating multiple single instances results in creating multiple copies of the server application. This option is commonly used for multiple document interface (MDI) applications.

b) Multiple Instance - specifies that multiple applications can connect to the object. Any time a client requests service, a separete instance of the server gets invoked. That is, there can be multiple instances in a single executable. For example, any time a user attempts to open the Windows Explorer, a separate Explorer is created

c) Internal - means the object can only be created internally. An external application cannot create an instance of the object directly. For example, a word processor application may have an internal document object that can only be created by calling a method of the application that will create the document object.

2. The Threading Model refers to how your object is advertised to the client applications via its thread support. You can select one from the next options: Single, Apartment, Free or Both.

a) Single - no thread support. Client requests are serialized by the standard calling mechanism. serialized by the calling mechanism. With this threading model the clients are handled one at a time so no threading
support is needed.

b) Apartment - different objects from the same server can be called on different threads or different clients, but each object is called only from that one thread. If two clients need to use the same object, they have to take turns. With this threading model the instance data is safe, global data must be protected using critical sections or some other form of serialization. Of course, the thread's local variables are reliable across multiple calls.

c) Free - clients can call any method of object from any thread at any time. Objects can handle any number of threads at any time. That is, more than one client can share the same object. Objects must protect all instance and global data using critical sections or some other form of serialization. Thread local variables are not reliable across multiple calls. Primarily used for distributed DCOM environments.

d) Both - objects can support clients that use either Aprtment or Free threading models. This threading model give a maximum performance and flexibility.

So a correct value selection of Instancing and Threading Model can affect on performance of your COM object and depends from task which you want realize in this object.

Initialize threads that interact with COM

Ever get the "CoInitialize has not been called" (800401F0 hex) error? Each thread in your application that interacts with COM (i.e. creates COM objects, calls COM APIs, etc.) must initialize itself into an apartment. A thread can either join a single threaded apartment (STA) or the multithreaded apartment (MTA). The STA is system-synchronized based on a windows message queue. Use the STA if your object or thread relies on thread-relative resources such as UI elements. The following shows how to initialize a thread into an STA: procedure FooThreadFunc;  //or TFooThread.Execute begin   CoInitializeEx (NIL, COINIT_APARTMENTTHREADED);   ... do your stuff here ...   CoUninitialize; end; The MTA is system-guaranteed to be ruthless. Objects in the MTA will receive incoming calls from anywhere anytime. Use the MTA for non-UI related objects, but synchronize carefully! The following shows how to initialize a thread into the MTA: procedure FooThreadFunc;  //or TFooThread.Execute begin   CoInitializeEx (NIL, COINIT_MULTITHREADED);   ... do your stuff here ...   CoUninitialize; end;