Understanding The COM Single-Threaded Apartment （1）

发布时间：2011-3-12 11:43
分类名称：COM

原文出自CodeProject，网上有人翻译过来，不过我觉得看原文会更加准确的了解概念。毕竟翻译是掺杂了一些译者的错误理解，而且和个人的汉语水平有些关系。

Introduction

Advanced COM-based projects often require the passing of objects across threads. Besides the requirement to invoke the methods of these objects from various threads, there is sometimes even the need to fire the events of these objects from more than one thread. This two-part article is aimed at the beginner level COM developer who has just crossed the initial hurdles of understanding the basics of IUnknown and IDispatch and is now considering the use of objects in multiple threads. This is where the need to understand COM Apartments come in.

I aim to explain in as much detail as possible the fundamental principles of how COM object methods may be invoked from multiple threads. We shall explore COM Apartments in general and the Single Threaded Apartment (STA) Model in particular in an attempt to demystify both what they are designed to achieve and how they achieve their design.

COM Apartments form a topic worthy of close study of its own. It is not possible to cover in detail everything that pertains to this subject in one single article. Instead of doing that, I will focus on Single-Threaded Apartments for now and will return to the other Apartment Models in later articles. In fact, I have found quite a lot of ground to cover on STAs alone and thus the need to split up this article into two parts.

This first part will concentrate on theory and understanding of the general architecture of STAs. The second part will focus on solidifying the foundations built up in part one by looking at more sophisticated examples.

I will present several illustrative test programs as well as a custom-developed C++ class named CComThread which is a wrapper/manager for a Win32 thread that contains COM objects or references to COM objects. CComThread also provides useful utilities that help in inter-thread COM method calls.

I will show how to invoke an object's methods from across different threads. I will also invoke an event of an object from another thread. Throughout this article, I will concentrate my explanations on Single Threaded Apartment COM objects and threads with some mention of other Apartment Models for comparison purposes. I chose to expound on the STA because this is the Apartment Model most frequently recommended by Wizards. The default model set by the ATL wizard is the STA. This model is useful in ensuring thread-safety in objects without the need to implement a sophisticated thread-synchronization infrastructure.

Synopsis

Listed below are the main sections of this article together with general outlines of each of their contents:

COM Apartments

This section gives a general introduction to COM Apartments. We explore what they are, what they are designed for, and why the need for them. We also discuss the relationship between apartments, threads and COM objects and learn how threads and objects are taught to live with each other in apartments.

The Single-Threaded Apartment

This section begins our in-depth study of the Single-Threaded Apartments and serves as a "warm-up" to the heavy-going sections that follow. We layout clearly the thread access rules of an STA. We also see how COM makes such effective use of the good old message loop. We then touch on the advantages and disadvantages of STAs in general before proceeding to discuss implementation issues behind the development of STA COM objects and STA threads.

Demonstrating The STA

This section and the next ("EXE COM Servers And Apartments") are filled with detailed descriptions of several test programs. This is the main aim of this article: to show concepts by clear examples. In this section, each test program is aimed at demonstrating one particular type of STA (beginners may be surprised to learn that there are actually three types of STAs !). The reader will note that our approach to demonstrating STAs is very simple. The challenge for me is to demonstrate clearly the different types of STAs using this simple test principle.

EXE COM Servers And Apartments

The last major section of this article explores EXE COM Servers and their relationship with Apartments. Some of the important differences between a DLL Server and an EXE Server are listed. From this section, I hope the reader gets to understand the important role that Class Factories play. I have deliberately written by hand the source codes used for the demonstration program in order to illustrate some concepts. The use of ATL Wizards will have made this more troublesome.

Without further ado, let us begin by exploring the principles behind the COM Apartments in general.

COM Apartments

To understand how COM deals with threads, we need to understand the concept of an apartment. An apartment is a logical container inside an application for COM objects which share the same thread access rules (i.e., regulations governing how the methods and properties of an object are invoked from threads within and without the apartment in which the object belongs).

It is conceptual in nature and does not present itself as an object with properties or methods. There is no handle type that can be used to reference it nor are there APIs that can be called to manage it in any way.

This is perhaps one of the most important reasons why it is so difficult for newbies to understand COM Apartments. It is so abstract in nature.

Apartments may have been much easier to understand and learn if there was an API named CoCreateApartment() (with a parameter that indicates the apartment type), and some other supporting APIs like CoEnterApartment(). It would have been even better still if there was a Microsoft supplied coclass with an interface like IApartment with methods that manage the threads and objects inside an apartment. Programmatically, there seem to be no tangible way to look at apartments.

To help the newbie cope with the initial learning curve, I have the following advise on the way to perceive apartments:

1. They are created by implication. There are no direct function calls to create them or to detect their presence.
2. Threads and objects enter apartments and engage in apartment-related activities also by implication. There are also no direct function calls to do so.
3. Apartment Models are more like protocols, or a set of rules to follow.

What Do COM Apartments Aim To Achieve?

In an operating environment in which multiple-threads can have legitimate access to various COM objects, how can we be sure that the results we expect from invoking the methods or properties of an object in one thread will not be inadvertently undone by the invocation of methods or properties of the same object from another thread?

It is towards resolving this issue that COM Apartments are created. COM Apartments exist for the purpose of ensuring something known as thread-safety. By this, we mean the safe-guarding of the internal state of objects from uncontrolled modification via equally uncontrolled access of the objects' public properties and methods running from different threads.

There are three types of Apartment Models in the COM world: Single-Threaded Apartment (STA), Multi-Threaded Apartment (MTA), and Neutral Apartment. Each apartment represents one mechanism whereby an object's internal state may be synchronized across multiple threads.

Apartments stipulate the following general guidelines for participating threads and objects:

• Each COM object is assigned to live in one and only one apartment. This is decided at the time the object is created at runtime. After this initial setup, the object remains in that apartment throughout its lifetime.
• A COM thread (i.e., a thread in which COM objects are created or COM method calls are made) also belongs to an apartment. Like COM objects, the apartment in which a thread lives is also decided at initialization time. Each COM thread also remains in their designated apartment until it terminates.
• Threads and objects which belong to the same apartment are said to follow the same thread access rules. Method calls which are made inside the same apartment are performed directly without any assistance from COM.
• Threads and objects from different apartments are said to play by different thread access rules. Method calls made across apartments are achieved via marshalling. This requires the use of proxies and stubs.

Besides ensuring thread-safety, another important benefit that Apartments deliver to objects and clients is that neither an object nor its client needs to know nor care about the Apartment Model used by its counterpart. The low-level details of Apartments (especially its marshalling mechanics) are managed solely by the COM sub-system and need not be of any concern to developers.

Specifying The Apartment Model Of A COM Object

From here onwards until the section "EXE COM Servers And Apartments" later on below, we will refer to COM objects which are implemented in DLL servers.

As mentioned, a COM object will belong to exactly one runtime apartment and this is decided at the time the object is created by the client. However, how does a COM object indicate its Apartment Model in the first place?

This setting is controlled by the developers of the COM object themselves. When you develop a COM object using ATL, for example, you can specify to the ATL Wizard the threading model the object is to use at runtime.

The table below shows the appropriate string values and the corresponding Apartment Model that each indicates:

We will be talking about the Legacy STA later on in this article. The "Both" string value indicates that the COM object can live equally well inside an STA and inside an MTA. That is, it can live in either model. We shall return to this registry entry in a later article after the MTA has been fully expounded.

Specifying The Apartment Model Of A COM Thread

Now, onto threads. Every COM thread must initialize itself by calling the API CoInitializeEx() and passing as the second parameter either COINIT_APARTMENTTHREADED or COINIT_MULTITHREADED.

A thread which has called CoInitializeEx() is a COM thread and is said to have entered an apartment. This will be so until the thread calls CoUninitialize() or simply terminates.

The Single-Threaded Apartment

An STA can contain exactly one thread (hence the term single-threaded). However, an STA can contain as many objects as it likes. The special thing about the thread contained within an STA is that it must, if the objects are to be exported to other threads, have a message loop. We will return to the subject of message loops in a sub-section later on and explore how they are used by STAs.

A thread enters an STA by specifying COINIT_APARTMENTTHREADED when it calls CoInitializeEx(), or by simply calling CoInitialize() (calling CoInitialize() will actually invoke CoInitializeEx() with COINIT_APARTMENTTHREADED). A thread which has entered an STA is also said to have created that apartment (after all, there are no other threads inside that apartment to first create it).

A COM object enters an STA both by specifying "Apartment" in the appropriate string value in the registry and by being instantiated inside an STA thread.

In the above diagram, we have two apartments. Each apartment contains two objects and one thread. We can postulate that each thread has, early in their life, called CoInitialize(NULL) or CoInitializeEx(NULL, COINIT_APARTMENTTHREADED).

We can also tell that Obj1, Obj2, Obj3 and Obj4 are each marked as of "Apartment" threading model in the registry, and that Obj1 and Obj2 were created inside Thread1 and Obj3 and Obj4 were created inside Thread2.

STA Thread Access Rules

The following are the thread access rules of an STA:

1. An STA object created inside an STA thread will reside in the same STA as its thread.
2. All objects inside an STA will receive method calls only from the thread of the STA.

Hence any method calls between Obj1 and Obj2 are considered cross-apartment and must be performed with COM marshalling.

Concerning point 2, there are only two ways that an STA object's methods are invoked:

1. From its own STA thread. In this case, the method call is naturally serialized.
2. From another thread (whatever the Apartment). In this case, COM ensures that the object will receive method calls only from its own STA thread by stipulating that this STA thread must contain a message loop.

We have mentioned this point about message loops previously, and before we can go on discussing the internals of STAs, we must cover the subject of message loops and see how they are intimately connected with STAs. This is discussed next.

The Message Loop

A thread that contains a message loop is also known as a user-interface thread. A user-interface thread is associated with one or more windows which are created in that thread. The thread is often said to own these windows. The window procedure for a window is called only by the thread that owns the window. This happens when the DispatchMessage() API is called inside the thread.

The benefit to Windows application developers is that window procedures need not be thread-safe. Each window message becomes an atomic action request which will be processed completely before the next message is entertained.

This presents to COM a readily available, built-in facility in Windows that can be used to achieve thread-safety for COM objects. Simply put, all method calls from external apartments to an STA object are accomplished by COM posting private messages to a hidden window associated with that object. The window procedure of that hidden window then arranges the call to the object and arranges the return value back to the caller of the method.

Note that when external apartments are involved, COM will always arrange for proxies and stubs to be involved as well so message loops form only part of the STA protocol.

There are two important points to note:

1. The above-mentioned system of using a message-loop to invoke STA COM object methods is only applicable when the calls are from an external apartment (whatever model it takes). Remember that calls made from inside an STA goes without any intervention by COM. These are naturally serialized by the execution sequence of the STA thread itself.
2. If an STA thread fails to get and dispatch the messages in its message queue, the COM objects in the thread's apartment will not receive incoming inter-apartment calls.

Concerning point 2, it is important to note that APIs like Sleep(), WaitForSingleObject(), WaitForMultipleObjects() will disrupt the flow of thread message handling. As such, if an STA thread needs to wait on some synchronization object, special handling will need to be arranged to ensure that the message loop is not disrupted. We shall examine how this can be done when we study our sample code later on.

Take note that in some circumstances, an STA thread need not contain a message loop. We will return to explain this in the section "Implementing an STA Thread" later on.

It should be clear now how an STA achieves its thread access rules.

Benefits Of Using STA

The main advantage to using an STA is simplicity. Besides a few basic code overheads for COM object servers, relatively few synchronization code is necessary for the participating COM objects and threads. All method calls are automatically serialized. This is especially useful for user-interface-based COM objects (a.k.a. COM ActiveX Controls).

Because STA objects are always accessed from the same thread, it is said to have thread affinity. And with thread affinity, STA object developers can use thread local storage to keep track of an object's internal data. Visual Basic and MFC use this technique for development of COM objects and hence are STA objects.

Besides using it for benefits, it is sometimes inevitable to use STAs when there is a need to support legacy COM components. COM components developed in the days of Microsoft Windows NT 3.51 and Microsoft Windows 95 could only use the Single-Threaded Apartment. Multi-Threaded Apartments became available for usage in Windows NT 4.0 onwards and in Windows 95 with DCOM extensions.

Disadvantages Of Using STA

There is a flip side to everything in life and there are disadvantages to using STA. The STA architecture can impose significant performance penalties when an object is accessed by many threads. Each thread's access to the object is serialized and so each thread must wait in line for its turn to have a go with the object. This waiting time may result in poor application response or performance.

The other issue which can result in poor performance is when an STA contains many objects. Remember that an STA contains only one thread and hence will contain only one thread message queue. This being the case, calls to separate objects within that STA will all be serialized by the message queue. Whenever a method call is made on an STA object, the STA thread may be busy servicing another object.

The disadvantages of using the STA must be measured against the possible advantages. It all depends on the architecture and design of the project at hand.

Implementing An STA COM Object And Its Server

Implementing an STA COM object generally frees the developer from having to serialize access to the object's internal member data. However, the STA cannot ensure the thread-safety of a COM server DLL's global data and global exported functions like DllGetClassObject() and DllCanUnloadNow(). Remember that a COM server's objects could be created in any thread and that two STA objects from the same DLL server can be created in two separate STA threads.

In this situation, the global data and functions of the server may well be accessed from two different threads without any serialization from COM. The message loops of the threads cannot lend any help either. After all, it is not an object's internal state that is at stake here. It is the server's internal state. Hence all access to global variables and functions of the server will need to be serialized properly because more than one object may try to access these from different threads. This rule also applies to class static variables and functions.

One well-known global variable of COM servers is the global object count. This variable is accessed by the equally well-known global exported functions DllGetClassObject() and DllCanUnloadNow(). The APIs InterlockedIncrement() and InterlockedDecrement() may be used to protect simultaneous access (from different threads) to the global object count. DllGetClassObject() will in turn make use of the class factories of COM objects and these must be examined for thread-safety too.

Hence the following is a general guideline for implementing STA Server DLLs:

1. Server DLLs must have thread-safe standard entry point functions (e.g., DllGetClassObject() and DllCanUnloadNow()).
2. Private (non-exported) global functions of the Server DLL must be thread-safe.
3. Private global variables (especially the global object count) must be thread-safe.

The purpose of the DllGetClassObject() function is to supply to callers a class object. This class object is returned based on a CLSID and will be referenced by a pointer to one of its interfaces (usually, IClassFactory). DllGetClassObject() is not called directly by COM object consumers. It is instead called from within the CoGetClassObject() API.

It is from this class object that instances of a CLSID is created (via IClassFactory::CreateInstance()). We can look at the DllGetClassObject() function as the gateway to the COM object creation. The important point to note about DllGetClassObject() is that it affects the global object count.

The DllCanUnloadNow() function returns a value to its caller that determines whether the COM Server DLL contains objects which are still alive and are servicing clients. This DllCanUnloadNow() function uses the global object count to decide its return value. If no more objects are still alive, the caller can safely unload the COM Server DLL from memory.

The DllGetClassObject() and DllCanUnloadNow() functions should be arranged for thread-safety such that at least the global object count is kept in synch. A common way that the global object count is incremented and decremented is when an object is created and destroyed respectively (i.e., during the constructor and destructor of the object's implementation). The following sample code illustrates this:

The above code snippets show how the global object counter "g_lObjsInUse" is incremented using the InterlockedIncrement() API during the constructor of an object implemented by the C++ class CSomeObject. Conversely, during the destructor of CSomeObject, "g_lObjsInUse" is decremented by the InterlockedDecrement() API.

No details can be advised on how to ensure the thread-safety of private global functions and global variables. This must be left to the expertise and experience of the developers themselves.

Ensuring thread-safety for a COM server need not be a complicated process. In many situations, it requires simple common sense. It is safe to say that the above guidelines are relatively easy to comply with and do not require constant re-coding once put in place. Developers using ATL to develop COM servers will have these covered for them (except for the thread-safety of private global data and functions) so that they can concentrate fully on the business logic of their COM objects.

Implementing An STA Thread

An STA thread needs to initialize itself by calling CoInitialize() or CoInitializeEx(COINIT_APARTMENTTHREADED). Next, if the objects it creates are to be exported to other threads (i.e., other Apartments), it must also provide a message loop to process incoming messages to the hidden windows of COM objects. Take note that it is the hidden windows' window procedures that receive and process these private messages from COM. The STA thread itself does not need to process the message.

The following code snippet presents the skeleton of an STA thread:

The code snippet above looks vaguely similar to a WinMain() function. In fact, the WinMain() of a Windows application runs in a thread too.

In fact, you can implement your STA thread just like a typical WinMain() function. That is, you can create windows just prior to the message loop and run your windows via appropriate window procedures. You may opt to create COM objects and manage them in these window procedures. Your window procedures may also make cross-apartment method calls to external STA objects.

However, if you do not intend to create windows inside your thread, you will still be able to create, run objects and make cross-apartment method calls across external threads. These will be explained when we discuss some of the advanced example codes in part two of this article.

Special cases where no message loop is required in an STA Thread

Take note that in some cases, a message loop is not required in an STA thread. An example of this can be seen in simple cases where an application simply creates and uses objects without having its objects marshaled to other apartments. The following is an example:

The above example shows the main thread of a console application in which an STA is established when we call CoInitialize(). Note that there is no message loop defined inside this thread. We also go on to create a COM object based on the ISimpleCOMObject1 interface. Note that our calls to Initialize() and Uninitialize() go successfully. This is because the method calls are made inside the same STA and no marshalling and no message loop is required.

However, if we had called ::CoInitializeEx(NULL, COINIT_MULTITHREADED) instead of CoInitialize(), thereby making the main() thread an MTA thread instead of an STA thread, four things will happen:

1. The calls to Initialize() and Uninitialize() will be made with the help of COM marshalling.
2. The COM object spISimpleCOMObject1 will reside in a default STA created by the COM sub-system.
3. The main() thread still does not need any message loop, but...
4. A message loop will be used in the calls to Initialize() and Uninitialize().

The message loop that is used in this context is the message loop that is defined in the default STA. We will talk about the default STA later on in the section on "The Default STA".

Note that whenever you do need to provide a message loop for an STA thread, then you must ensure that this message loop is serviced constantly without disruption.

Demonstrating The STA

We will now attempt to demonstrate STAs. The approach we use is to observe the ID of the thread which is executing when a COM object's method is invoked. For a standard STA object, this ID must match that of the thread of the STA.

If an STA object does not reside in the thread in which it is created (i.e., this thread is not an STA thread), then the ID of this thread will not match that of the thread which executes the object's methods. This basic principle is used throughout the examples of this article.

The Standard STA

Let us now observe STAs in action. To start, we examine the standard STA. A process may contain as many standard STAs as is required. Our example uses a simple example STA COM object (coclass SimpleCOMObject2 which implements interface ISimpleCOMObject2). The source for this STA object is located in the "SimpleCOMObject2" folder in the ZIP file accompanying this article. The ISimpleCOMObject2 interface includes just one method: TestMethod1().

TestMethod1() is very simple. It displays a message box which shows the ID of the thread in which the method is running on:

We will also be using a sample test program which instantiates coclass SimpleCOMObject2 and calls its method. The source for this test program can be found in the folder "Test Programs\VCTests\DemonstrateSTA\VCTest01" in the source ZIP file.

The test program consists of a main() function ...:

... a thread entry point function named ThreadFunc():

... and a utility function named DisplayCurrentThreadId() that shows a message box displaying the ID of the currently running thread:

The above example shows the creation of two STAs. We prove it by way of thread IDs. Let us go through the program carefully, starting with the main() function:

1. The main() function calls the CoInitializeEx() API with parameter COINIT_APARTMENTTHREADED. This makes main()'s thread enter an STA. From here onwards, any STA object created in main()'s thread will be part of the STA headed by main()'s thread.
2. We call the function DisplayCurrentThreadId(). The ID of main()'s thread is displayed. Let's say this is thread_id_1.
3. Next, an instance of coclass SimpleCOMObject2 is created (represented by spISimpleCOMObject2). This object is an STA object and so it will be in the same STA as main()'s thread.
4. The TestMethod1() method is invoked on spISimpleCOMObject2. TestMethod1() will display the ID of the thread in which TestMethod1() is executing in. You will note that this will be thread_id_1. That is, it will be the same as main()'s thread ID. Next, we start a thread headed by the entry function ThreadFunc(). Thereafter, we wait for ThreadFunc() to end by calling the WaitForSingleObject() API and waiting on the handle of the ThreadFunc() thread.
5. In the ThreadFunc() thread, we invoke the CoInitializeEx() API with parameter COINIT_APARTMENTTHREADED. This makes ThreadFunc()'s thread enter an STA. Note that this STA is different from main()'s STA. This is a second STA of the process.
6. We call on DisplayCurrentThreadId() and note that the thread ID of ThreadFunc()'s thread is indeed different. Let's say this is thread_id_2.
7. We next create two instances of coclass SimpleCOMObject2 (spISimpleCOMObject2A and spISimpleCOMObject2B).
8. We then call the TestMethod1() method of spISimpleCOMObject2A and spISimpleCOMObject2B.
9. The IDs of the threads that are running when the TestMethod1() methods are invoked from spISimpleCOMObject2A and spISimpleCOMObject2B are displayed one at a time.
10. You will note that this ID will be the same as the thread ID of ThreadFunc(). That is, it will be displayed as thread_id_2.
11. The ThreadFunc() thread will come to an end and we will return to main().
12. We once again invoke the TestMethod1() method on spISimpleCOMObject2 to show that nothing has changed for spISimpleCOMObject2. TestMethod1() will still run on main()'s thread (i.e., ID: thread_id_1).

What we have demonstrated here is the straightforward creation of two STAs which were initialized by main()'s thread and by ThreadFunc()'s thread. main()'s STA then proceeds to contain the STA object spISimpleCOMObject2. ThreadFunc()'s thread will also contain the STA objects spISimpleCOMObject2A and spISimpleCOMObject2B. The following example illustrates the above:

An important point to note is that spISimpleCOMObject2, spISimpleCOMObject2A and spISimpleCOMObject2B are all instances of the same coclass yet it is possible that they reside in separate STAs. For a standard STA object, what matters is which STA first instantiates it.

Notice also in this example that we had not supplied any message loops in both main() and ThreadFunc(). They are not needed. The objects in both STAs are used within their own Apartments and are not used across threads. We even included a call to WaitForSingleObject() in main() and it did not cause any trouble. There were no occasions to use the hidden windows of these STA objects. No messages were posted to these hidden windows and so no message loops were needed.

In the next section, we will discuss something known as the Default STA. We will also demonstrate it by example codes. The examples will also enhance the validity of the above example which we have just studied.

The Default STA

What happens when an STA object gets instantiated inside a non-STA thread? Let us look at a second set of example codes which will be presented below. This new set of source codes are listed in "Test Programs\VCTests\DemonstrateDefaultSTA\VCTest01". It also uses the example STA COM object of coclass SimpleCOMObject2 (implements interface ISimpleCOMObject2) which was seen in the last example. The current example also uses the utility function DisplayCurrentThreadId() that shows a message box displaying the ID of the thread currently running.

Let's examine the code:

Let us go through the program carefully:

1. The main() function calls on CoInitializeEx(NULL, COINIT_MULTITHREADED). This way, main()'s thread initializes itself as belonging to an MTA.
2. We next call DisplayCurrentThreadId(). The ID of main()'s thread will be displayed.
3. Next, an STA object spISimpleCOMObject2 is instantiated inside this thread.
4. Note that spISimpleCOMObject2 is an STA object which is instantiated inside a non-STA thread. spISimpleCOMObject2 will not reside in the MTA and will instead be created inside a default STA.
5. We call TestMethod1() on spISimpleCOMObject2. You will note that the ID of the thread in which TestMethod1() executes is not the same as main()'s thread.

What happened was that spISimpleCOMObject2 will live inside a default STA. All STA objects in a process which are created inside non-STA threads will reside in the default STA.

As can be seen in the above diagram, since spISimpleCOMObject2 lives in the default STA and not within main()'s MTA, main()'s call to spISimpleCOMObject2 -> TestMethod1() is an inter-apartment method call. This requires marshalling, and hence what main() receives from COM is not an actual pointer to spISimpleCOMObject2 but a proxy to it.

And since inter-apartment calls are actually performed, the default STA must contain a message loop. This is provided for by COM.

Developers new to the world of COM Apartments please note well this intriguing phenomenon: that even though a call to CreateInstance() or CoCreateInstance() is made inside a thread, the resulting object can actually be instantiated in another thread. This is performed transparently by COM behind the scenes. Please therefore take note of this kind of subtle maneuvering by COM especially during debugging.

Let us now look at a more sophisticated example. This time, we use the sources listed in "Test Programs\VCTests\DemonstrateDefaultSTA\VCTest02". This new set of sources also use the same STA COM object of coclass SimpleCOMObject2 (implements interface ISimpleCOMObject2) which was seen in the last example. The current example also uses the utility function DisplayCurrentThreadId() that shows a message box displaying the ID of the thread currently running when this function is invoked.

Let's examine the code:

Let us go through the program carefully:

1. The main() function calls CoInitializeEx(NULL, COINIT_MULTITHREADED) thereby making main()'s thread enter an MTA.
2. We call DisplayCurrentThreadId() and note the ID of main()'s thread. Let's say this is thread_id_1.
3. We then instantiate coclass SimpleCOMObject2 which implements interface ISimpleCOMObject2. This object is spISimpleCOMObject2.
4. We call TestMethod1() of this STA object. The ID of the thread under which TestMethod1() executes will be displayed. You will note that this id will not be thread_id_1. That is, it will not be the same as main()'s thread ID. Let's say this ID is thread_id_2.
5. We then start a second thread, executing with the entry function ThreadFunc(), which initializes itself as belonging to an MTA.
6. The ID of this second thread will be displayed when we call DisplayCurrentThreadId(). Let's say this is thread_id_3.
7. Two STA objects of coclass SimpleCOMObject2 (implementing ISimpleCOMObject2) are instantiated inside this second thread.
8. We call TestMethod1() of the two STA objects inside the second thread. You will see that the ID of the thread in which TestMethod1() executes will not be thread_id_3. That is, it will not be the same as the ID of ThreadFunc()'s thread.
9. Instead, the ID of the thread in which TestMethod1() executes is actually thread_id_2! That is, it runs in the same thread as spISimpleCOMObject2 of main().

What we have shown here is a more complicated example of the creation and use of the default STA. spISimpleCOMObject2 is an STA object that got instantiated inside a non-STA thread (main()'s thread). spISimpleCOMObject2A and spISimpleCOMObject2B were also instantiated inside a non-STA thread (ThreadFunc()'s thread). Therefore, all three objects spISimpleCOMObject2, spISimpleCOMObject2A and spISimpleCOMObject2B will all reside in the default STA which is first created when spISimpleCOMObject2 is created.

I strongly encourage the reader to modify the source codes and see different results. Change one or more ::CoInitializeEx() calls from using COINIT_APARTMENTTHREADED to COINIT_MULTITHREADED and vice versa. Put a breakpoint in "CSimpleCOMObject2::TestMethod1()" to see the difference when it is invoked from an STA thread and when it is invoked from an MTA thread.

These calls are part of the marshalling code put in motion during inter-apartment calls.

The Legacy STA

There is another type of default STA known as the Legacy STA. This STA is where the legacy COM objects will reside in. By legacy, we mean those COM components that have no knowledge of threads whatsoever. These objects must have their ThreadingModel registry entry set to "Single" or have simply left out any ThreadingModel entry in the registry.

The important point to note about these Legacy STA objects is that all instances of these objects will be created in the same STA. Even if they are created in a thread initialized with ::CoInitializeEx(NULL, COINIT_APARTMENTTHREADED), they will still live and run in the legacy STA if it has already been created.

The legacy STA is usually the very first STA created in a process. If a legacy STA object is created before any STA is created, one will be created by the COM sub-system.

The advantage of developing a legacy STA object is that all access to all instances of such objects are serialized. You do not need any inter-apartment marshalling between any two legacy STA objects. However, non-legacy STA objects living in non-legacy STAs that want to make calls to legacy-STA objects must, nevertheless, arrange for inter-apartment marshalling. The converse (legacy-STA objects making calls to non-legacy STA objects living in non-legacy STAs) also requires inter-apartment marshalling. Not a very attractive advantage, I think.

Let us showcase two examples. The first example we will cover uses an example Legacy STA COM object of coclass LegacyCOMObject1. The source codes for this COM object is listed in "LegacyCOMObject1". This COM object functions similarly with the COM object of coclass SimpleCOMObject2 which we have seen in previous examples. LegacyCOMObject1 also has a method named TestMethod1() which also displays the ID of the thread in which the TestMethod1() function is executing.

The test program which uses LegacyCOMObject1 has its source codes listed in "Test Programs\VCTests\DemonstrateLegacySTA\VCTest01". This current test program also uses the same utility function DisplayCurrentThreadId() that shows a message box displaying the ID of the thread currently running when this function is invoked.

Let us take a look at the code of the test program:

Here, I added a call to ::CoInitializeEx(NULL, COINIT_APARTMENTTHREADED) together with a commented out call to ::CoInitializeEx(NULL, COINIT_MULTITHREADED). I added in the commented out code to easily illustrate the effects when main()'s thread is a non-STA thread. Simply uncomment this code (and comment the code above it!) and see different results. More on this later.

Let us go through the program carefully:

1. The thread running main() enters a standard STA.
2. We display the ID of main()'s thread. Let's say this is thread_id_1.
3. We then create a Legacy STA object of coclass LegacyCOMObject1.
4. We call the Legacy STA object's TestMethod1() method.
5. The ID of the thread in which TestMethod1() is running is displayed.
6. You will find that this thread ID will be thread_id_1.

What happened in the above example is simple: spILegacyCOMObject1, a Legacy STA object, gets instantiated inside the very first STA created in the process (which is main()'s STA). main()'s STA is therefore designated a Legacy STA and spILegacyCOMObject1 will live inside this Legacy STA. Note well: the first STA created in a process is special because it is also the Legacy STA.

If we had switched the parameter to COINIT_MULTITHREADED, as in the following:

The following would be the outcome:

1. The thread running main() enters an MTA.
2. We display the ID of main()'s thread. Let's say this is thread_id_1.
3. We then create a Legacy STA object of coclass LegacyCOMObject1.
4. We call the Legacy STA object's TestMethod1() method.
5. The ID of the thread in which TestMethod1() is running is displayed.
6. You will find that this thread ID will not be thread_id_1.

What happened in the above example is also straightforward: spILegacyCOMObject1, a Legacy STA object, gets instantiated inside an MTA. It cannot live inside this MTA and so COM creates a default Legacy STA. spILegacyCOMObject1 will therefore live inside this COM generated Legacy STA.

A Legacy STA object behaves very much like a standard STA object as the above two examples show. However, there is a difference: all Legacy STA objects can only be created inside the same STA thread. We will demonstrate this with yet another example code.

The next example code also uses the same LegacyCOMObject1 object which was demonstrated in the last example. This current test program also uses the same utility function DisplayCurrentThreadId() that shows a message box displaying the ID of the thread currently running when this function is invoked. The example code is listed in "Test Programs\VCTests\DemonstrateLegacySTA\VCTest02".

A new utility function named ThreadMsgWaitForSingleObject() makes its debut here. It is a cool function which is useful in many applications. I shall document this function in part two of this article as it deserves close attention on its own. For now, simply note that ThreadMsgWaitForSingleObject() will allow a thread to wait on a handle while at the same time service any messages that comes its way. It encapsulates the functionality of a message loop as well as that of WaitForSingleObject(). This function will prove very useful for us as you will see in the example code.

Let us take a look at the code of the test program:

Let us go through the program carefully:

1. The thread executing main() enters an STA.
2. We display the ID of the main() thread. Let's say this thread ID is thread_id_1.
3. We create an instance of coclass LegacyCOMObject1 (spILegacyCOMObject1).
4. We invoke TestMethod1() of spILegacyCOMObject1.
5. The ID of the thread executing TestMethod1() is displayed. You will note that this is thread_id_1.
6. We then start a thread headed by ThreadFunc(). Thereafter, we wait for this thread to finish by calling ThreadMsgWaitForSingleObject().
7. The ThreadFunc() thread is initialized as a non-STA thread.
8. In the ThreadFunc() thread, we instantiate two instances of coclass LegacyCOMObject1 (spILegacyCOMObject1A and spILegacyCOMObject1B).
9. We call TestMethod1() on spILegacyCOMObject1A and spILegacyCOMObject1B.
10. The ID of the thread executing each call to TestMethod1() is revealed. You will note that this is thread_id_1.
11. The ThreadFunc() thread will then complete and we return to main()'s thread.
12. We call TestMethod1() of spILegacyCOMObject1 and note that the ID of the thread executing TestMethod1() of spILegacyCOMObject1 has not changed. It is still thread_id_1.

Let us analyze this latest test program. The thread executing main() enters a standard STA. This STA is the first STA created in the process. Recall that the first STA created in a process is also the Legacy STA, hence the main()'s STA is the Legacy STA. Now, spILegacyCOMObject1 (in main()) is created as a normal STA object and it resides in the same STA as the one just created in main().

When the second thread (headed by ThreadFunc()) starts up, it is started as an MTA. Hence any STA object created inside this thread cannot live in this MTA (it cannot use ThreadFunc()'s thread). Both spILegacyCOMObject1A and spILegacyCOMObject1B are STA objects and hence they cannot live inside ThreadFunc()'s MTA. Now, if spILegacyCOMObject1A and spILegacyCOMObject1B are normal STAs, a new STA will be created for them to live in. However, they are Legacy STAs and so they must live in the legacy STA (if one already exists, and one already does exist).

The end result is that they will be accommodated in the Legacy STA created in main()'s thread. This is why, when you invoke TestMethod1() from ThreadFunc(), the call is actually marshaled to main()'s thread. There is actually inter-apartment marshalling between ThreadFunc()'s MTA apartment (where the TestMethod1() call originates) and main()'s STA apartment (where the TestMethod1() call is executed).