Understanding The COM Single-Threaded Apartment （2）

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

Note point 3 in the diagram: "The creation call is marshaled by COM into the Legacy STA". In order for the creation call to be successful, COM has to communicate with the Legacy STA and tell it to create spILegacyCOMObject1A. This communication requires a message loop to exist in the target Legacy STA. Hence the need for the services of ThreadMsgWaitForSingleObject().

EXE COM Servers And Apartments

Thus far, we have discussed COM servers implemented inside DLLs. However, this article will not be complete without touching on COM servers implemented in EXEs. My aim is to show how Apartments, the STA in particular, are implemented inside an EXE server. Let us start with examining two of the main differences between a DLL server and an EXE server.

Difference 1: The Way Objects Are Created

When COM wishes to create a COM object which is implemented inside a DLL, it loads the DLL, connects with its exported DllGetClassObject() function, calls it, and obtains a pointer to the IClassFactory interface of the class factory object of the COM object. It is from this IClassFactory interface pointer that the COM object is created.

The story with EXE Servers has the same eventuality: obtaining the IClassFactory interface pointer of the class factory object of the COM object to be created and then creating the COM object through it. What happens before that is the difference between a DLL server and an EXE Server.

A DLL server exports the DllGetClassObject() function for COM to extract the class factory but an EXE server cannot export any function. An EXE server instead has to register its class factory in the COM sub-system when it starts up, and then revoke the class factory when it shuts down. This registration is done via the API CoRegisterClassObject().

Difference 2: The Way The Apartment Model Of Objects Are Indicated

As mentioned earlier in this article, objects implemented in DLLs indicate their Apartment Models by appropriately setting the "ThreadingModel" registry string value which is located in the object's "InProcServer32" registry entry.

Objects implemented in an EXE server do not set this registry value. Instead, the Apartment Model of the thread which registers the object's class factory determines the object's Apartment Model:

In the above code snippet, we are attempting to register a class factory for the CLSID_ExeObj02 COM object inside a thread. Note the call to ::CoInitializeEx(NULL, COINIT_APARTMENTTHREADED) at the beginning. This call indicates to COM that CLSID_ExeObj02 COM objects will live in an STA. The thread which called CoRegisterClassObject() is the lone thread inside this STA. This implies that there will be a message loop inside this thread and that all access to any CLSID_ExeObj02 object created by any client are serialized by this message loop.

If the call to CoInitializeEx() used COINIT_MULTITHREADED instead, CLSID_ExeObj02 COM objects will live in an MTA. This means that CLSID_ExeObj02 COM objects and its class factory object can be accessed from any thread. Such threads can be those which are implemented internally in the EXE Server (as part of the logic of the implementation) or those from the RPC thread pool the purpose of which is to serve external clients' method calls. The implementation of the CLSID_ExeObj02 COM object must therefore ensure internal serialization to whatever extent required. In many ways, this is much more efficient as compared with STAs.

Aside from the above two differences, take note that while it is possible that STA objects inside a DLL server receive method calls only from inside its owning STA thread, all method calls from a client to an STA object inside an EXE COM server will invariably be invoked from an external thread. This implies the use of marshalling proxies and stubs and, of course, a message loop inside the object's owning STA thread.

Demonstrating The STA Inside A COM EXE Server

As usual, we shall attempt to demonstrate STAs inside COM EXE Servers via an example code. The example code for this section is rather elaborate. It can be found in the following folder: "Test Programs\VCTests\DemonstrateExeServerSTA" in the sample code that accompanies this article. There are three parts to this set of sample code:

1. Interface ("Interface\ExeServerInterfaces" subfolder).
2. Implementation ("Implementation\ExeServerImpl" subfolder).
3. Client ("Client\VCTest01" subfolder).

Please note that in order to use the ExeServerImpl COM server, you will need to compile code in "Implementation\ExeServerImpl" and then register the resultant ExeServerImpl.exe by typing the following command in a command prompt window:

Do not type any "-" or "\" before "RegServer".

The Interface

The code in the Interface part is actually an ATL project ("ExeServerInterfaces.dsw") which I use to define three interfaces: IExeObj01, IExeObj02 and IExeObj03. The three interfaces each contain only one single method (of the same name): TestMethod1(). This ATL project also specifies three coclasses which are identified by CLSID_ExeObj01 (specified to contain an implementation of interface IExeObj01), CLSID_ExeObj02 (specified to contain an implementation of interface IExeObj02) and CLSID_ExeObj03 (specified to contain an implementation of interface IExeObj03).

There is no meaningful implementation of these interfaces and coclass's in this project. I created this project in order to use the ATL wizards to help me manage the IDL file and to automatically generate the appropriate "ExeServerInterfaces.h" and "ExeServerInterfaces_i.c" files. These generated files are used by both the Implementation and Client code.

I used a separate ATL project to generate the above-mentioned files because I wanted my implementation code to be non-ATL based. I wanted a COM EXE implementation based on a simple Windows application so that I could put in various customized constructs that can help me illustrate STAs clearer. With the ATL wizards, things can be a little more inflexible.

The Implementation

The code in the Implementation part provides an implementation of the interfaces and coclass's described in the Interface part. Except for CExeObj02, each of the implementation of TestMethod1() contains only a message box display:

The purpose of doing this is to show the ID of the thread which is executing when each of the methods is invoked. This should match with the ID of their containing STA thread. I have made CExeObj02 a little special. This C++ class provides an implementation of IExeObj02. It also contains a pointer to an IExeObj01 object:

During the construction of CExeObj02, we will instantiate m_pIExeObj01:

The purpose of doing this is to show later that CExeObj02 and the object behind m_pIExeObj01 will run in separate STAs. Take a look at this class' TestMethod1() implementation:

Two message boxes will be displayed: the first one showing CExeObj02's thread ID and the second will show m_pIExeObj01's thread ID. These IDs will be different as will be seen later on when we run the client code.

In addition to providing implementations to the interfaces, the implementation code also provide class factories for each of the coclass's. These are CExeObj01_Factory, CExeObj2_Factory and CExeObj03_Factory.

Let us now focus our attention on the WinMain() function:

I have left out some code in WinMain() that pertains to EXE server registration and unregistration which are not relevant to our discussion here. I have narrowed down the code to show only the runtime class factory registration process.

I created two helper functions RegisterClassObject() and RegisterClassObject_ViaThread() to help me with simplifying the call to CoRegisterClassObject().

These are simple helper functions and, to avoid digression, I will not discuss them in this article but to provide only a summary of what these functions do:

• RegisterClassObject() - instantiates a class factory based on the class name (supplied as a template parameter) and then registers this class factory to COM as the class factory for a COM object the CLSID of which is supplied as a parameter to the RegisterClassObject() function.
• RegisterClassObject_ViaThread() - starts a thread whose job is to register a class factory using the RegisterClassObject() function.

Whenever the EXE COM Server starts up, it registers all three class factories (albeit not all of them are performed in WinMain()'s thread).

Notice the call to CoInitializeEx(NULL, COINIT_APARTMENTTHREADED) at the beginning of the function. This is important and it makes the COM objects created by the class factory registered in WinMain()'s thread belong to an STA (the one in which WinMain()'s thread is currently running in). This class factory is CExeObj01_Factory and the CLSID of the objects it creates is CLSID_ExeObj01.

After performing class factories registration, WinMain() enters a message loop. This message loop services all method calls to CLSID_ExeObj01 COM objects created by clients.

Let us now observe the other threads in action:

Each of the threads perform the same actions:

1. Each initializes itself as an STA thread by calling CoInitializeEx(NULL, COINIT_APARTMENTTHREADED).
2. Each displays the ID of the thread in which it is running (DisplayCurrentThreadId()).
3. Each registers a class factory for CExeObj02_Factory and CExeObj03_Factory respectively.
4. Each enters a message loop.

What we obtain eventually can be summarized in the following table:

The Client

Let us move on now to the Client. The Client code is simple. It consists of a main() function that instantiates two instances each of coclass'es CLSID_ExeObj01, CLSID_ExeObj02 and CLSID_ExeObj03. Each instantiation is referenced by a pointer to interfaces IExeObj01, IExeObj02 and IExeObj03 respectively:

Note our call to CoInitializeEx(NULL, COINIT_MULTITHREADED) at the beginning of main(). Unlike the case with using DLL servers, this call will have no effect on the Apartment Model used by the COM objects that we create.

The Client code then proceeds to call each interface pointer's TestMethod1() method before releasing all interface pointers:

Let us observe what will happen when the Client application runs:

1. When the first call to ::CoCreateInstance() is made, COM will launch our EXE COM server.
2. Our COM server will then run its WinMain() function. The first visible thing it will do is to display WinMain()'s thread ID in a message box. Let's say this is thread_id_1.
3. Next, the class factory for the CLSID_ExeObj01 COM object is registered within WinMain()'s thread. Hence CLSID_ExeObj01 COM objects will live in the STA headed by WinMain()'s thread.
4. Our COM server will then launch the thread headed by ThreadFunc_RegisterExeObj02Factory() which will register the class factory for the CLSID_ExeObj02 COM object. The ID for this thread is displayed by a message box at the start of the thread. Let's say this is thread_id_2.
5. CLSID_ExeObj02 COM objects will live in the STA headed by the thread with ID thread_id_2.
6. Our COM server will then launch the thread headed by ThreadFunc_RegisterExeObj03Factory() which will register the class factory for the CLSID_ExeObj03 COM object. The ID for this thread is displayed by a message box at the start of the thread. Let's say this is thread_id_3.
7. CLSID_ExeObj03 COM objects will live in the STA headed by the thread with ID thread_id_3.
8. Back to the client code. When TestMethod1() is invoked on pIExeObj01A, the ID of the thread which is executing is displayed. You will note that this is thread_id_1 which is consistent with point 3 above.
9. The same ID will be displayed when TestMethod1() is invoked on pIExeObj01B.
10. When TestMethod1() is invoked on pIExeObj02A, two thread IDs will be displayed one after the other. The first one is the ID of the thread executing when pIExeObj02A -> TestMethod1() is invoked, and this is thread_id_2 which is consistent with point 5 above.
11. When the second message box is displayed, we will see the ID of the thread running when the CLSID_ExeObj01 COM object contained inside pIExeObj02A is invoked. This is not thread_id_2 but thread_id_1! This is perfectly in line with point 3 above.
12. The same pair of IDs will be displayed when TestMethod1() is invoked on pIExeObj02B.
13. When pIExeObj03A -> TestMethod1() and pIExeObj03B -> TestMethod1() are invoked in the statements that follow, we will see that the ID of the thread executing them is thread_id_3. This is again consistent with point 7 above.

If you were to put breakpoints in CExeObj01::TestMethod1() and CExeObj02::TestMethod1(), you will observe from the call stack that calls between them are actually marshaled.

We have thus demonstrated STAs as used inside a COM EXE Server. I strongly encourage the reader to experiment with the code and see the effects of changing one or more threads from STAs to MTAs. It's a fun way to learn.

Before I conclude this last major section, please allow me to present two short variations to the Implementation code. The first shows the dramatic effects of not providing the appropriate message loop inside a class registration thread. The second shows the completely harmless effects of not providing one!

Variation 1

Let us examine the first case. In the EXE COM server code's main.cpp file, we modify the ThreadFunc_RegisterExeObj02Factory() function as follows:

We simply add a Sleep() statement right above the message loop. Compile the EXE COM server again. Run the client in debug mode (so that you can observe what happens when coclass CLSID_ExeObj02 is instantiated as in the following call to CoCreateInstance()):

You will note that this call will appear to hang. But hold on, if you had patiently waited for about 20 seconds, the call will go through. What happened? Well, turns out that because CLSID_ExeObj02 is an STA object, the call to CoCreateInstance() resulted in a need to communicate with the message loop of the thread that registered the CLSID_ExeObj02 class factory.

By blocking the thread with a Sleep() statement, the thread's message loop does not get serviced. The call to create instance will not return in this case. But once the Sleep() statement returns, the message loop is started and the create instance call is serviced and will return in time.

Note therefore the importance of the message loop in a COM EXE Server STA thread.

Variation 2

This time, let us modify the ThreadFunc_RegisterExeObj02Factory() function as follows:

This time, we change the thread into an MTA thread, set Sleep()'s parameter to INFINITE, and comment out the message loop altogether.

You will find that the call to ::CoCreateInstance() on coclass CLSID_ExeObj02 in the client will go through successfully albeit CLSID_ExeObj02 is now an MTA object and the calls to its TestMethod1() method may display different thread IDs.

What we have shown clearly here is that as long as the MTA thread that registers a class factory remains alive (via Sleep(INFINITE)), calls to the class factory goes through (without the need for any message loop, by the way).

Note that regardless of whether ThreadFunc_RegisterExeObj02Factory() is an STA or MTA thread, if it had fallen through and exited after registering its class factory, unpredictable results will occur when coclass CLSID_ExeObj02 is instantiated in the client.

In Conclusion

I certainly hope that you have benefited from the explanatory text as well as the example code of this long article. I have done my level best to be as thorough and exhaustive as possible to lay a strong foundation on the concepts of Single-Threaded Apartments.

In this part one, I have demonstrated a few inter-apartment method calls for which COM has already paved the way. We have also seen how COM automatically arranges for objects to be created in the appropriate apartment threads. Proxies and stubs are generated internally and the marshalling of proxies are performed transparently without the developers' knowledge.

In part two, we will touch on more advanced features of COM that pertain to STAs. We shall show how to perform explicit marshaling of COM object pointers from one apartment to another. We will also show how an object can fire events from an external thread. Lower-level codes will be explored.

Acknowledgements And References

• The Essence of COM, A Programmer's Workbook (3^rd Edition) by David S. Platt. Published by Prentice Hall PTR.
• Inside COM by Dale Rogerson. Published by Microsoft Press.
• Essential COM by Don Box. Published by Addison-Wesley.