IDevResource.com COM channel - Threads and Apartments

The Developer's Resource & Community Site

COM	XML	ASP	Java & Misc.	NEW: VS.NET
International	This Week	Forums	Author Central	Find a Job

Threads and Apartments

Author: Brad Wilson
Date Submitted: Feb 04 2000
Level of Difficulty: Intermediate
Subjects Covered: Single Threaded Apartments, Multi Threaded Apartments, Apartments.
Pre-required Reading:

Table of Contents

  Introduction
  What is a threading model?
  What is an apartment?
  The single threaded apartment
  The multithreaded apartment
  Matching threading models and apartments
  A word about pumping messages and reentrancy
  So what's "both" threading?
  How do I set the threading model in ATL?
  Recommended reading
  About the author

Introduction:

This article is intended for the new COM developer. It gives detailed information about apartments and their relationship to threading and synchronization. The goal is to demystify what is a very important, yet under-documented system in COM.

What is a threading model?

COM has a very powerful model of thinking (which is extended with MTS and again with COM+). The model is this: components have a “context” in which they run, which is configured to meet their needs.

When you specify a threading model, you are telling COM what type of runtime environment your object expects, with respect to multithreaded access. COM provides four separate threading models, each with a distinct threading requirement:

Single Threaded

The single threaded model is the original model, and the only one supported in 16-bit Windows (obviously, since Windows 3.x doesn’t support threads). In the single threaded model, COM guarantees that all accesses to all instances of your objects will occur on a single thread.

Apartment Threaded

Apartment threading is available on all 32-bit Windows platforms except Win32s (again, because Windows 3.x doesn’t support threading). In the apartment threaded mode, COM guarantees that all access to a single instance of your object will occur on a single thread, but multiple instances may be created into multiple different threads.

Free Threaded

Free threading is available on all 32-bit Windows platforms with DCOM. Windows NT 4.0, Windows 98, and Windows 2000 all support free threading natively; Windows 95 requires the DCOM service pack to support free threading. In the free threaded mode, COM allows multiple threads to access a single instance of your object.

Both Threaded

The both threaded model is a special model that’s best understood once you have a good grasp of all the other threading models, and rules involved therein. It will be addressed at the end of this article.

What is an apartment?

In order to enforce the threading rules, the COM team invented the idea of an apartment. This is the “environment” that an individual instance of an object runs in.

In COM, there are two types of apartments: the single threaded apartment (abbreviated “STA”), and the multithreaded apartment (abbreviated “MTA”). In addition, there is a special kind of STA called the “Main STA”. The Main STA is the first STA created in a given process.

Each thread that wants to use COM must initialize itself with COM. At the time that it initializes itself, it declares what type of apartment should be associated with that thread.

If you call CoInitialize() (or its OLE counterpart, OleInitialize()), then you are telling the system to create a single threaded apartment for you and associate it the thread. You can call CoInitialize() on any system that supports COM.

If you call CoInitializeEx(), then you can explicitly specify the type of apartment as one of the flags in the second parameter. If you specify COINIT_MULTITHREADED, the COM runtime will associate the thread with the MTA; if you specify COINIT_APARTMENTTHREADED, the COM runtime will associate the thread with an STA. You can only call CoInitializeEx on systems that have DCOM installed.

The single threaded apartment

The single threaded apartment, as its name implies, only allows a single thread to run in it. For every thread that calls CoInitializeEx with COINIT_APARTMENTTHREADED (or CoInitialize or OleInitialize), the COM runtime creates a new single threaded apartment for the thread. Therefore, a process can have multiple single threaded apartments.

The first single threaded apartment created in a process is also known as the Main STA. We’ll talk about the significance of the Main STA in a moment.

When an object is created into an STA, it is guaranteed that no other threads will access it but the thread that created it. That means an object created into an STA can safely use Thread Local Storage (TLS) to store information that is specific to the instance of the object.

An object which has a threading model of “single” will always be created into the Main STA, even if the thread that created it is already in an STA. That’s because the “single” threading model guarantees that all instances of the objects will be accessed from a single thread. COM makes this guarantee by always creating “single” threaded objects into the Main STA. “Single” threaded objects do not need to synchronize any data, because of this guarantee.

An object that has a thread model of “apartment” will always be created into an STA. However, each individual object may be created into a different STA, so any static, global or shared data between instances of objects must be synchronized, since these things may be accessed from multiple threads.

The multithreaded apartment

The multithreaded apartment, unlike the STA, permits multiple threads to be in it at one time. There is at most one multithreaded apartment in a process. The first thread that enters the multithreaded apartment, or the first multithreaded object that’s created, causes the multithreaded apartment to be created. Subsequence threads that enter the MTA and multithread objects will all enter the same, single MTA.

When an object is created into the MTA, there are no reentrancy guarantees. An object that lives in the multithreaded apartment may be called by any number of threads simultaneously, and is responsible for synchronizing not only the global, static, and shared data, but also the instance data in the object.

Something that’s also not very obvious to the beginning COM user is that objects in the MTA may be called at any time from threads they’ve never seen before. First, there is the fact that one thread in the MTA could create the object, then pass its pointer off to another thread in the MTA. Additionally, the RPC runtime creates threads when out of process calls arrive, and this RPC threads can directly call into MTA objects. An object in the MTA should not use TLS to store any state specific data, and should shield its data from concurrent access by different threads through some kind of serialization constructs.

Matching threading models and apartments

When a thread initializes COM, it declares the type of apartment it wishes to live in. When creating objects, if it creates components that can happily live in the apartment it’s in, it will get direct pointers to the objects.

So, what happens when the object’s threading model doesn’t conform to the apartment the current thread is in? The system creates the object in the type of context it expects to be in, and then passes back a pointer to a “proxy”.

The “proxy” concept is too large to address in this article. It is an important issue, so you should educate yourself on them. For the purposes of this discussion, just assume that a proxy lives in your apartment, and knows how to route your calls to the real object that’s living in another apartment.

Object creation from an STA

If the thread is in an STA, and creates an “apartment” threaded object, it is created in the threads apartment, and a direct pointer is passed back.

If the thread is in an STA, and creates a “single” threaded object, the COM runtime creates the object into the main STA. If this thread’s apartment is the Main STA, then it returns a direct pointer; otherwise, it returns a proxy.

If the thread is in an STA, and creates a “free” threaded object, then the COM runtime will look to see if the MTA has been created for this process yet. If not, it will create one. Then it creates a new object into the MTA, and passes back a proxy.

Object creation from the MTA

If the thread is in an MTA, and creates a “free” threaded object, the COM runtime creates the object into the MTA, and returns a direct pointer.

If the thread is in an MTA, and creates a “single” or “apartment” threaded object, then the COM runtime checks to see if the Main STA has been created yet. If not, it creates the Main STA. It then creates the object into the Main STA, and returns a proxy.

A word about pumping messages and reentrancy

When a thread is in the MTA, the system truly blocks when a call goes through a proxy. Because multiple threads can enter the MTA, this blocking isn’t a problem, because the RPC runtime can always create a new thread to call into the object if there is a callback.

However, when a thread is in the STA, it cannot block, because the method call it makes via the proxy may result in a callback. If the thread is blocked, it will never be able to service the callback, and the two objects go into deadlock. So how does the COM runtime deal with this?

The answer is: messages. When calling out of an STA via a proxy, the thread “pseudo-blocks”; that is, it continues to pump messages for the thread. When the RPC service gets a call into the thread for a COM object, it services that call via the message loop. This prevents the deadlock situation.

It’s important for threads in an STA to pump messages if they need to receive COM messages. Otherwise, a deadlock situation can occur.

Also notice that this means that even a “single” threaded object can be reentered because of a callback. While this typically isn’t a major problem for most objects, you need to ensure that a callback isn’t going to corrupt the state of your object.

So, what’s “both” threading?

The “both” threading model indicates that a component is willing to run in either an STA or an MTA. Since any object that can run in an MTA is fully synchronized, it seems logical that any object that can be “free” threaded, can also be “both” threaded. So, why would you ever use “free” threading? Isn’t the win of not using a proxy reason enough to always use “both” threading?

The answer is not always. COM components, of course, can also be COM clients. One object may create any number of objects to help it perform its work. An object may also create threads that perform work for it, and call back into the object.

If the object were marked as “both” threaded, and then created on a thread that was in an STA, it would be created in that STA. Then, any free threaded components it needed to access would be created in the MTA, and a proxy would be returned. All calls between the objects would be marshaled.

The issue of worker threads is less obvious for the new COM developer. What’s so bad about creating a worker thread that calls back into an object, no matter what apartment it’s in? As long as the object can handle calls from multiple threads, it should be okay, right?

No! Imagine a situation where a “both” threaded object is created into an STA, and creates worker threads that call back into it. The worker threads take a direct pointer to the object, and when their work is done, it calls back into the object. The object is synchronized, so it can handle this “cheat”. What happens, though, if the result of the method call from the thread into the object results in a method call into another component that the object has created?

Well, if you’re lucky, you have a proxy, and the RPC layer will tell you you tried to call from the wrong thread, and rejects the call. If you’re not so lucky, you’ll have a direct pointer, call into the object, and possibly crash it horribly, because it wasn’t designed to run multithreaded (you’re in the STA, after all!)

So, choosing between “free” and “both” threading models depends on the type of work that the component is going to be doing. If the object does its work on its own without much assistance from other components, then it is an excellent candidate for the “both” threading model. If, however, it relies on free threaded components or worker threads, it should restrict itself to the “free” threading model for performance reasons.

How do I set the threading model in ATL?

When you do raw COM programming, all you need to do is ensure that your object performs the right kind of threading support, and register the threading model in the registry.

When you use ATL 3.0 to build your COM components, there are a few steps you should take to ensure that your components are set for the correct threading model.

1. Change the #define in stdafx.h

Open stdafx.h in your project, and change the #define that sets your default threading model. By default, the line reads:


#define _ATL_APARTMENT_THREADED

You want to change it to _ATL_SINGLE_THREADED or _ATL_FREE_THREADED as appropriate. If you have multiple components in your project with different threading models, default the one that requires the most synchronization; eg, if you have some free threaded components, use _ATL_FREE_THREADED; if you have some apartment threaded components, but no free threaded, then use _ATL_SINGLE_THREADED.

2. Change the threading model class you derive from

Open the header file for the C++ class that implements your component. In the inheritance tree, your first class that you inherit is typically:


public
CComObjectRootEx<CComSingleThreadModel>

The template parameter that you provide to CComObjectRootEx is the type of threading model that your component uses. It should be CComSingleThreadModel for “single” or “apartment” threaded components, and CComMultiThreadModel for “free” or “both” threaded components.

3. Change the .RGS file

Open the .RGS file for your component. In it you will see a line that resembles:


val ThreadingModel = s ‘Apartment’

Change the value to ‘Single’, ‘Apartment’, ‘Free’ or ‘Both’ as appropriate.

4. Make sure you understand the implications!

The most important thing to changing threading models is to understand the implications it has on the run time environment of your component. This is by far the easiest thing to forget. I’ve seen more than my fair share of components that ran fine in apartment mode, that suddenly get buggy in free threaded mode, because access to a state variable wasn’t synchronized.

More COM Library articles:

CAtlBitmapButton - ATL/WTL Ownerdraw Superclassed Bitmap Button By Amit Dey.
Amit describes building a simple user interface consisting of a series of bitmap buttons in a dialog.
Author: Amit Dey
Date Submitted: June 8 2001

ATL COM and ADO By Paddy Srinivas.
COM+ Events addresses many shortcomings of Connection points. Paddy Srinivas walks us through the COM+ Events System.
Author: Paddy Srinivas
Date Submitted: March 7 2001

ATL COM and ADO By Amit Dey.
New author Amit Dey (he's looking for a job BTW ;-) ) explains his recent experiences with ATL COM and ADO. He simply explains the fundamentals of ADO and then runs through some ATL code examples in his application.
Author: Amit Dey
Date Submitted: March 6 2001

COM Singletons: A Dangerous Animal By Richard Blewett.
Richard Blewitt simply explains the use of COM Singletons.
Author: Richard Blewett
Date Submitted: January 24 2001

ASP COM Objects By Jan Verhoeven.
Creating ASP com objects, or Active Server Objects with Delphi 5 is very easy, once you know how to do it.
Author: Jan Verhoeven
Date Submitted: November 1 2000

SafeArrays - For the Beginner By A. Abdul Azeez.
This article is a primer to Safe Arrays and can be used by any beginner to Safe Arrays.
Author: A. Abdul Azeez
Date Submitted: November 1 2000

COM+ Basics - Creating your first COM+ Application By Martin Lapierre.
Author: Martin Lapierre
Date Submitted: June 1 2000

COM+ - the backbone of Windows DNA By Mahesh Bhide.
Author: Mahesh Bhide
Date Submitted: June 1 2000

Exploring COM Threading and Apartments By Anthony Toivonen.
Anthony Toivonen wants you to figure it out for yourself: he guarantees success in threads and apartments after reading this article.
Author: Anthony Toivonen
Date Submitted: May 17th 2000

COM on Linux By Frank Rem.
A description of how to code a DCOM client for Linux without using Microsoft products.
Author: Frank Rem
Date Submitted: May 17th 2000

ATL Server By Richard Grimes.
A description of ATL Server.
Author: Richard Grimes
Date Submitted: May 9th 2000

ATL Internals - Part 2 By Shivesh Viswanathan.
Following on from Shivesh's first article of this two part series, this article covers the details of the internals of ATL.
Author: Shivesh Viswanathan
Date Submitted: May 3rd 2000

How to use DDX with WTL By Girish Bharadwaj.
Author: Girish Bharadwaj
Date Submitted: March 27th 2000

COM Patterns By Tony Toivonen.
Author: Tony Toivonen
Date Submitted: March 27th 2000

COM+ Object Pooling By Jeremiah Talkar.
Author: Jeremiah Talkar
Date Submitted: March 23rd 2000

What are COM Pipes? By Richard Grimes.
Author: Richard Grimes
Date Submitted: March 23rd 2000

Java COM Integration - Use Visual J++ to implement COM Objects By Gopalan Suresh Raj.
Author: Gopalan Suresh Raj
Date Submitted: March 9th 2000

Developing an MSMQ Server Application using VJ++ By Gopalan Suresh Raj.
Author: Gopalan Suresh Raj
Date Submitted: March 9th 2000

Developing an MSMQ Client using VJ++ By Gopalan Suresh Raj.
Author: Gopalan Suresh Raj
Date Submitted: March 9th 2000

What is Async COM? By Richard Grimes.
Author: Richard Grimes
Date Submitted: March 8th 2000

Coding a DCOM Server Component from IDL By Gopalan Suresh Raj.
Author: Gopalan Suresh Raj
Date Submitted: February 10th 2000
Level of Difficulty: Advanced
Subjects Covered: IDL, DCOM, J++
Pre-required Reading: Component Object Model

Coding a DCOM Client By Gopalan Suresh Raj.
Author: Gopalan Suresh Raj
Date Submitted: February 10th 2000
Level of Difficulty: Advanced
Subjects Covered: IDL, DCOM, J++
Pre-required Reading: Component Object Model, Coding a DCOM Server Component from IDL

Threads and Apartments By Brad Wilson.
Brad's article gives detailed information about apartments and their relationship to threading and synchronization. The goal is to demystify what is a very important, yet under-documented system in COM.
Author: Brad Wilson
Date Submitted: Feb 04 2000
Level of Difficulty: Intermediate
Subjects Covered: Single Threaded Apartments, Multi Threaded Apartments, Apartments.
Pre-required Reading:

WTL Architecture By Richard Grimes.
This article covers the basics of the WTL architecture, it describes the types of applications that you can create and how WTL manages threads. The example monitors the debug stream and uses WTL to present this data.
Author: Richard Grimes
Date Submitted: Feb 02 2000
Level of Difficulty: Intermediate
Subjects Covered: WTL applications architecture, WTL UI update, OutputDebugString and debugging API
Pre-required Reading: assumes a knowledge of ATL and of Win32 application development (for example "Professional ATL COM Programming", Richard Grimes, Wrox Press)

The MTS Series by Gopalan Suresh Raj:

Microsoft Transaction Server By Gopalan Suresh Raj.
Gopalans introductory article on Microsoft Transaction Server introduces the basics to MTS, and leads in to the example articles included in the series.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: None

Developing a Simple MTS Server Component By Gopalan Suresh Raj.
Part 1 of a two part example.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: Microsoft Transaction Server

Developing a Simple MTS Client Application By Gopalan Suresh Raj.
Part 2 of a two part example.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: Microsoft Transaction Server, Developing a Simple MTS Server Component

Developing The Bank Account IDL By Gopalan Suresh Raj.
A Three-Tier Architecture for a Bank Checking Account - Developing The Bank Account IDL is part 1 of a 3 part example.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: Microsoft Transaction Server

MTS Server Component By Gopalan Suresh Raj.
A Three-Tier Architecture for a Bank Checking Account - MTS Server Component is the second part of this three part example.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: Microsoft Transaction Server, Developing The Bank Account IDL

MTS Client By Gopalan Suresh Raj.
A Three-Tier Architecture for a Bank Checking Account - MTS Server Component is the third part of this three part example.
Author: Gopalan Suresh Raj
Date Submitted: Jan 26 2000
Level of Difficulty: Beginners / Intermediate
Subjects Covered: MTS
Pre-required Reading: Microsoft Transaction Server, Developing The Bank Account IDL, MTS Server Component