CComMultiThreadModel Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CComMultiThreadModel Class.

CComMultiThreadModel` provides thread-safe methods for incrementing and decrementing the value of a variable.

Syntax

class CComMultiThreadModel

Members

Public Typedefs

Name	Description
CComMultiThreadModel::AutoCriticalSection	References class CComAutoCriticalSection.
CComMultiThreadModel::CriticalSection	References class CComCriticalSection.
CComMultiThreadModel::ThreadModelNoCS	References class CComMultiThreadModelNoCS.

Public Methods

Name	Description
CComMultiThreadModel::Decrement	(Static) Decrements the value of the specified variable in a thread-safe manner.
CComMultiThreadModel::Increment	(Static) Increments the value of the specified variable in a thread-safe manner.

Remarks

Typically, you use CComMultiThreadModel through one of two typedef names, either [CComObjectThreadModel](../Topic/ATL%20Typedefs.md#ccomobjectthreadmodel or [CComGlobalsThreadModel](../Topic/ATL%20Typedefs.md#ccomglobalsthreadmodel. The class referenced by each typedef depends on the threading model used, as shown in the following table:

typedef	Single threading	Apartment threading	Free threading
CComObjectThreadModel	S	S	M
CComGlobalsThreadModel	S	M	M

S= CComSingleThreadModel; M= CComMultiThreadModel

CComMultiThreadModel itself defines three typedef names. AutoCriticalSection and CriticalSection reference classes that provide methods for obtaining and releasing ownership of a critical section. ThreadModelNoCS references class CComMultiThreadModelNoCS.

Requirements

Header: atlbase.h

CComMultiThreadModel::AutoCriticalSection

When using CComMultiThreadModel, the typedef name AutoCriticalSection references class CComAutoCriticalSection, which provides methods for obtaining and releasing ownership of a critical section object.

typedef CComAutoCriticalSection AutoCriticalSection;

Remarks

CComSingleThreadModel and CComMultiThreadModelNoCS also contain definitions for AutoCriticalSection. The following table shows the relationship between the threading model class and the critical section class referenced by AutoCriticalSection:

Class defined in	Class referenced
CComMultiThreadModel	CComCriticalSection
CComSingleThreadModel	CComFakeCriticalSection
CComMultiThreadModelNoCS	CComFakeCriticalSection

In addition to AutoCriticalSection, you can use the typedef name CriticalSection. You should not specify AutoCriticalSection in global objects or static class members if you want to eliminate the CRT startup code.

Example

The following code is modeled after CComObjectRootEx, and demonstrates AutoCriticalSection being used in a threading environment.

template< class ThreadModel >
class CMyAutoCritClass
{
public:
   typedef ThreadModel _ThreadModel;
   typedef typename _ThreadModel::AutoCriticalSection _CritSec;

   CMyAutoCritClass() : m_dwRef(0) {}

   ULONG InternalAddRef()
   {
      return _ThreadModel::Increment(&m_dwRef);
   }
   ULONG InternalRelease()
   {
      return _ThreadModel::Decrement(&m_dwRef);   
   }
   void Lock() { m_critsec.Lock( ); }
   void Unlock() { m_critsec.Unlock(); }

private:
   _CritSec m_critsec;
   LONG m_dwRef;
};

The following tables show the results of the InternalAddRef and Lock methods, depending on the ThreadModel template parameter and the threading model used by the application:

ThreadModel = CComObjectThreadModel

Method	Single or Apartment Threading	Free Threading
InternalAddRef	The increment is not thread-safe.	The increment is thread-safe.
Lock	Does nothing; there is no critical section to lock.	The critical section is locked.

ThreadModel = CComObjectThreadModel::ThreadModelNoCS

Method	Single or Apartment Threading	Free Threading
InternalAddRef	The increment is not thread-safe.	The increment is thread-safe.
Lock	Does nothing; there is no critical section to lock.	Does nothing; there is no critical section to lock.

CComMultiThreadModel::CriticalSection

When using CComMultiThreadModel, the typedef name CriticalSection references class CComCriticalSection, which provides methods for obtaining and releasing ownership of a critical section object.

typedef CComCriticalSection CriticalSection;

Remarks

CComSingleThreadModel and CComMultiThreadModelNoCS also contain definitions for CriticalSection. The following table shows the relationship between the threading model class and the critical section class referenced by CriticalSection:

Class defined in	Class referenced
CComMultiThreadModel	CComCriticalSection
CComSingleThreadModel	CComFakeCriticalSection
CComMultiThreadModelNoCS	CComFakeCriticalSection

In addition to CriticalSection, you can use the typedef name AutoCriticalSection. You should not specify AutoCriticalSection in global objects or static class members if you want to eliminate the CRT startup code.

Example

See CComMultiThreadModel::AutoCriticalSection.

CComMultiThreadModel::Decrement

This static function calls the Win32 function InterlockedDecrement, which decrements the value of the variable pointed to by p.

static ULONG WINAPI Decrement(LPLONG p) throw ();

Parameters

p
[in] Pointer to the variable to be decremented.

Return Value

If the result of the decrement is 0, then Decrement returns 0. If the result of the decrement is nonzero, the return value is also nonzero but may not equal the result of the decrement.

Remarks

InterlockedDecrement prevents more than one thread from simultaneously using this variable.

CComMultiThreadModel::Increment

This static function calls the Win32 function InterlockedIncrement, which increments the value of the variable pointed to by p.

static ULONG WINAPI Increment(LPLONG p) throw ();

Parameters

p
[in] Pointer to the variable to be incremented.

Return Value

If the result of the increment is 0, then Increment returns 0. If the result of the increment is nonzero, the return value is also nonzero but may not equal the result of the increment.

Remarks

InterlockedIncrement prevents more than one thread from simultaneously using this variable.

CComMultiThreadModel::ThreadModelNoCS

When using CComMultiThreadModel, the typedef name ThreadModelNoCS references class CComMultiThreadModelNoCS.

typedef CComMultiThreadModelNoCS ThreadModelNoCS;

Remarks

CComMultiThreadModelNoCS provides thread-safe methods for incrementing and decrementing a variable; however, it does not provide a critical section.

CComSingleThreadModel and CComMultiThreadModelNoCS also contain definitions for ThreadModelNoCS. The following table shows the relationship between the threading model class and the class referenced by ThreadModelNoCS:

Class defined in	Class referenced
CComMultiThreadModel	CComMultiThreadModelNoCS
CComSingleThreadModel	CComSingleThreadModel
CComMultiThreadModelNoCS	CComMultiThreadModelNoCS

Example

See CComMultiThreadModel::AutoCriticalSection.

See Also

CComSingleThreadModel Class
CComAutoCriticalSection Class
CComCriticalSection Class
Class Overview