Mcl C++ Class Library Reference

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation

Copyright © <Dates> by <Authors>. All Rights Reserved.


Introduction

Mcl C++ Class Library Reference ››

MCL C++ Class Library Reference

The Mcl class library provides an object-oriented interface for multithreaded programming on the Win32 operating systems. Mcl contains C++ wrappers for critical sections, the thread, mutex, semaphore, and event kernel objects, as well as helper classes and higher-level classes useful in multithreaded applications.

CMclAutoLock

CMclCondition

CMclCritSec

CMclDerivedAutoPtr

CMclEvent

CMclEventAutoPtr

CMclIsValidHandle

CMclKernel

CMclKernelAutoPtr

CMclLinkedList

CMclLinkedList::CMclLinkedListDataNode

CMclLinkedList::CMclLinkedListNode

CMclLinkedList::CMclLinkedListSentinelNode

CMclMailbox

CMclMonitor

CMclMutex

CMclMutexAutoPtr

CMclQueue

CMclSemaphore

CMclSemaphoreAutoPtr

CMclSharedMemory

CMclStack

CMclThread

CMclThreadAutoPtr

CMclThreadHandler

CMclThrowError

CMclWaitAbandoned

CMclWaitAbandonedIndex

CMclWaitableCollection

CMclWaitableObject

CMclWaitFailed

CMclWaitSucceeded

CMclWaitSucceededIndex

CMclWaitTimeout

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


CMclAutoLock Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclAutoLock Description

Mcl C++ Class Library Reference ›› CMclAutoLock Class ››

CMclAutoLock [Declaration] [Implementation]

class CMclAutoLock

This class automates the act of acquiring and releasing a critical section or mutex by entering a given critical section (or acquiring a given mutex) in the class constructor. The class destructor then automatically leaves the given critical section (or releases the given mutex) when it is invoked. Because destructors for local objects declared on the stack are automatically invoked during the global unwind that takes place when an exception occurs, using this class will ensure that a critical section or mutex is automatically released when an exception occurs.

CMclAutoLock Class Members

Public Non-Virtual Methods

CMclAutoLock | Enters a given critical section or acquires a given mutex
~CMclAutoLock | Automatically leaves the specified critical section or releases the mutex

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


CMclAutoLock::CMclAutoLock

Mcl C++ Class Library Reference ›› CMclAutoLock Class ››

CMclAutoLock::CMclAutoLock

CMclAutoLock( HANDLE hMutexHandle );

CMclAutoLock( CMclMutex& rCMclMutex );

CMclAutoLock( CRITICAL_SECTION * pCritSec );

CMclAutoLock( CMclCritSec& rCMclCritSec );

Four versions of the class constructor are provided for convenience. The first form of the constructor accepts a raw Win32 HANDLE to a mutex kernel object. The second form of the constructor accepts a reference to a CMclMutex object. The third form of the constructor accepts a pointer to a Win32 CRITICAL_SECTION structure. The fourth form of the constructor accepts a reference to a CMclCritSec object. The CMclAutolock class remembers which form of the constructor was called and takes appropriate action in the class destructor.

Comments

The calling thread will be blocked until either the specified critical section can be entered or the specified mutex can be acquired.

See Also:

~CMclAutoLock class destructor

Win32 EnterCriticalSection and WaitForSingleObject functions

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclAutoLock::~CMclAutoLock

Mcl C++ Class Library Reference ›› CMclAutoLock Class ››

CMclAutoLock::~CMclAutoLock

~CMclAutoLock();

Automatically leaves the critical section that was specified in the third or fourth form of the class constructor, or releases the mutex that was specified in the first and second form of the constructor.

See Also:

CMclAutoLock class constructor

Win32 LeaveCriticalSection and ReleaseMutex functions

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclCondition Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free Kindle producer


CMclCondition Description

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition [Declaration] [Implementation]

class CMclCondition

Friends

class CMclMonitor

This class is an abstract base class for use with the CMclMonitor synchronization object. It encapsulates the idea of waiting on an arbitrary Boolean condition, and cannot be instantiated directly. The Condition member is a pure virtual method that must be implemented in a derived class.

CMclCondition Class Members

Public Non-Virtual Methods

CMclCondition

Constructor for a condition object

Public Virtual Methods

~CMclCondition

Destructor for a condition object

Private Non-Virtual Methods

SignalEvent | Releases one waiting thread
WaitForEvent | Waits on an object’s internal event

Private Virtual Methods

Condition

Arbitrary Boolean condition procedure

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclCondition::CMclCondition

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition::CMclCondition

CMclCondition();

Constructs the condition object base class.

Comments

Internally, the constructor initializes an auto-reset event member object that is used to synchronize threads waiting on the Boolean condition implemented in the Condition procedure.

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


CMclCondition::~CMclCondition

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition::~CMclCondition

virtual ~CMclCondition();

Destroys the condition object.

Created with the Personal Edition of HelpNDoc: Easily create EPub books


CMclCondition::Condition

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition::Condition

virtual BOOL Condition( void ) = 0;

This is an abstract method that needs to be implemented in the derived class. The condition procedure is invoked in an inherently thread-safe manner. It is only called by a thread that is inside the monitor and thus is synchronized between threads.

Return Values

TRUE

The Boolean condition expression that this object encapsulates is TRUE.

FALSE

The Boolean condition expression that this object encapsulates is FALSE.

Comments

Any type of arbitrary condition procedure can be implemented in this function. In general, a derived class will have to add member variables that are necessary for the Condition procedure to compute the Boolean expression. Usually it is easiest to initialize these new member variables by providing values as arguments to the derived class constructor.

See Also:

CMclMonitor class documentation

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclCondition::SignalEvent

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition::SignalEvent

void SignalEvent( void );

Releases one thread waiting on the CMclCondition object’s internal event.

Comments

This procedure is used by the CMclMonitor class when the monitor detects that a CMclCondition object’s Condition procedure returns TRUE. It shouldn’t be called outside the CMclMonitor class by the programmer.

See Also:

CMclMonitor class documentation

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclCondition::WaitForEvent

Mcl C++ Class Library Reference ›› CMclCondition Class ››

CMclCondition::WaitForEvent

void WaitForEvent( void );

Causes the calling thread to wait until it is released by the internal event object's becoming signaled.

Comments

This procedure is used by the CMclMonitor class when a thread requests to wait on a CMclCondition object. It shouldn’t be called outside the CMclMonitor class by the programmer.

See Also:

CMclMonitor class documentation

Created with the Personal Edition of HelpNDoc: Create HTML Help, DOC, PDF and print manuals from 1 single source


CMclCritSec Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free EPub and documentation generator


CMclCritSec Description

Mcl C++ Class Library Reference ›› CMclCritSec Class ››

CMclCritSec [Declaration] [Implementation]

class CMclCritSec

This class provides a wrapper around the Win32 critical section API that takes care of initializing a new Win32 CRITICAL_SECTION when the object is instantiated, and deleting the CRITICAL_SECTION when the object is destroyed. CMclCritSec objects can also be used with the CMclAutoLock helper class. Critical sections can be used for thread synchronization between threads within the same process.

CMclCritSec Class Members

Public Non-Virtual Methods

CMclCritSec | Initializes a new Win32 critical section
Enter | Enters the critical section
GetCritSec | Returns a pointer to the underlying Win32 CRITICAL_SECTION object
Leave | Leaves the critical section

Public Virtual Methods

~CMclCritSec

Deletes the Win32 critical section object

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclCritSec::CMclCritSec

Mcl C++ Class Library Reference ›› CMclCritSec Class ››

CMclCritSec::CMclCritSec

CMclCritSec();

Calls the Win32 InitializeCriticalSection function to initialize a new critical section.

Comments

The critical section is initially unowned when it is constructed.

See Also:

The CMclMutex class for thread synchronization between threads in different processes.

The Win32 InitializeCriticalSection function.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclCritSec::~CMclCritSec

Mcl C++ Class Library Reference ›› CMclCritSec Class ››

CMclCritSec::~CMclCritSec

virtual ~CMclCritSec();

Calls the Win32 DeleteCriticalSection function to delete the Win32 CRITICAL_SECTION object that was initialized by the class constructor.

Comments

The critical section should be unowned at the time the critical section is deleted. The destructor does not automatically release the critical section if it is owned at the time the destructor executes.

See Also:

The Win32 DeleteCriticalSection function

Created with the Personal Edition of HelpNDoc: Full-featured Documentation generator


CMclCritSec::Enter

Mcl C++ Class Library Reference ›› CMclCritSec Class ››

CMclCritSec::Enter

void Enter( void );

Enters the critical section if it is not owned by another thread. If the critical section is currently owned by a different thread at the time this function is called, the calling thread is blocked until the owning thread exits the critical section. The CMclCritSec::Leave function is used to leave a critical section.

Comments

If the calling thread has already called CMclCritSec::Enter to enter the critical section, this function will not block the calling thread. However, the CMclCritSec::Leave function must be called the same number of times that Enter was called before the critical section will be released.

See Also:

The CMclCritSec::Leave function.

The Win32 EnterCriticalSection function.

Created with the Personal Edition of HelpNDoc: Free EPub producer


CMclCritSec::Leave

Mcl C++ Class Library Reference ›› CMclCritSec Class ››

CMclCritSec::Leave

void Leave( void );

Leaves a critical section that is owned by the calling thread.

Comments

Threads should only call this function after using the CMclCritSec::Enter function to enter a critical section. If the Enter member function was called multiple times by the calling thread, this function must be called the same number of times before the critical section will be released.

See Also:

The CMclCritSec::Enter function.

The Win32 LeaveCriticalSection function.

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclDerivedAutoPtr Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


CMclDerivedAutoPtr Description

Mcl C++ Class Library Reference ›› CMclDerivedAutoPtr Class ››

CMclDerivedAutoPtr [Declaration] [Implementation]

template<class T>

class CMclDerivedAutoPtr : public CMclKernelAutoPtr

Parameters

T

Class name of the type of object derived from CMclKernel that the derived class will manage. This can be CMclThread, CMclMutex, CMclSemaphore, CMclEvent, or any class derived from these classes.

CMclDerivedAutoPtr Class Members

Public Non-Virtual Methods

CMclDerivedAutoPtr | Class contructor
operator = | Type-safe assignment operator
operator -> | Type-safe dereferencing operator
operator * | Type-safe indirection operator

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator


CMclDerivedAutoPtr::CMclDerivedAutoPtr

Mcl C++ Class Library Reference ›› CMclDerivedAutoPtr Class ››

CMclDerivedAutoPtr::CMclDerivedAutoPtr

CMclDerivedAutoPtr( T *pObjectPtr = NULL );

This is a type-safe version of the CMclAutoPtr constructor. Its only function is to guarantee that the object pointer is of the correct type before using it to initialize the base class.

Returns

Description of return value for return values that are not enumerated types of one kind or another.

Parameters

pObjectPtr

Optional pointer to a dynamically created CMclKernel derived object of type T, which will be accessed and managed by this auto-pointer.

See Also:

CMclKernelAutoPtr class constructor

Created with the Personal Edition of HelpNDoc: Full-featured Help generator


CMclDerivedAutoPtr::operator *

Mcl C++ Class Library Reference ›› CMclDerivedAutoPtr Class ››

CMclDerivedAutoPtr::operator *

T & operator*() const;

Type-safe auto-pointer indirection operator

Returns

A reference to the managed object of the correct type

Comments

This operator allows auto-pointers to use the * operator with a syntax identical to regular pointers. It is type-safe and returns an object of the correct type for this instantiation of the CMclDerivedAutoPtr template class.

See Also:

CMclDerivedAutoPtr::operator -> member

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CMclDerivedAutoPtr::operator =

Mcl C++ Class Library Reference ›› CMclDerivedAutoPtr Class ››

CMclDerivedAutoPtr::operator =

CMclDerivedAutoPtr<T> & operator= ( T *pObjectPtr );

This is a type-safe assignment operator for auto-pointers. Its only function is to guarantee that the object pointer is of the correct type before forwarding it to the base class Reset member function.

Returns

A reference to the auto-pointer itself

Parameters

pObjectPtr

A pointer to a dynamically created object derived from CMclKernel, or NULL. Any currently managed object will be deleted. If the parameter is NULL, the currently managed object will be deleted and the auto-pointer reset to the null state. If the parameter refers to the same object as the auto-pointer is already managing, the managed object will not be deleted.

See Also:

CMclKernelAutoPtr::Reset member function

Created with the Personal Edition of HelpNDoc: Full-featured Documentation generator


CMclDerivedAutoPtr::operator ->

Mcl C++ Class Library Reference ›› CMclDerivedAutoPtr Class ››

CMclDerivedAutoPtr::operator ->

T * operator->() const;

Type-safe auto-pointer dereferencing operator

Returns

A pointer to the managed object, which is then dereferenced by the member name following the operator.

Comments

This operator allows auto-pointers to use the -> operator with a syntax identical to regular pointers. It is type-safe and returns an object of the correct type for this instantiation of the CMclDerivedAutoPtr template class.

See Also:

CMclDerivedAutoPtr::operator * member

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


CMclEvent Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclEvent Description

Mcl C++ Class Library Reference ›› CMclEvent Class ››

CMclEvent [Declaration] [Implementation]

class CMclEvent : public CMclKernel

This class provides a wrapper around the Win32 event kernel object services. As with the CMclMutex and CMclSemaphore classes, this class provides two forms of constructor that either creates or opens a Win32 event kernel object. Likewise, the destructor automatically takes care of calling CloseHandle to release the reference to the underlying kernel object. And as with the other kernel object wrapper classes, threads can wait for an event object to become signaled by calling the CMclKernel::Wait or CMclKernel::WaitForTwo member functions.

CMclEvent Class Members

Public Non-Virtual Methods

CMclEvent | Creates or opens a Win32 event kernel object
Pulse | Momentarily signals the event object in order to release any threads currently waiting on it, then automatically resets the event
Reset | Resets the event object to the nonsignaled state
Set | Signals the event object

Created with the Personal Edition of HelpNDoc: Full-featured EPub generator


CMclEvent::CMclEvent

Mcl C++ Class Library Reference ›› CMclEvent Class ››

CMclEvent::CMclEvent

CMclEvent( BOOL bManualReset = FALSE, BOOL bInitialState = FALSE, LPCTSTR lpName = NULL, LPSECURITY_ATTRIBUTES lpEventAttributes = NULL);

CMclEvent( LPCTSTR lpName, BOOL bInheritHandle = FALSE, DWORD dwDesiredAccess = EVENT_ALL_ACCESS);

The first form of the constructor will create a new event object or open an existing event object if one by the same name already exists. The second form of the constructor will open an event if it already exists, but will not create one if it does not.

Parameters

bManualReset

Indicates the type of event to create. Specify TRUE to create a manual reset event, or FALSE to create an auto reset event. If the named event exists and is opened, this parameter is ignored.

bInitialState

Indicates the initial state of a newly create event object. Specify TRUE to create a new event that is initially signaled. Specify FALSE to create a new event that is initially nonsignaled. If the named event exists and is opened, this parameter is ignored.

lpName

Specifies the name of an event to create or open. This parameter may be NULL when using the first form of the class constructor. This parameter must be supplied when using the second form of the constructor.

lpEventAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies access rights to a newly created event. This parameter may be NULL if the default security attributes for an event are desired.

bInheritHandle

Indicates whether or not the handle returned for the event can be inherited by child processes spawned by the calling process. Specify TRUE to make the handle inheritable. Specify FALSE to prevent the handle from being inherited.

dwDesiredAccess

Indicates the desired access the calling thread would like to the event. If the security attributes for an existing event do not allow threads in the calling process to have the specified access, then the event cannot be opened.

Comments

The CMclKernel::Status member function can be called to determine the success or failure of the constructor. If the first form of the constructor is used, the Status function will return ERROR_ALREADY_EXISTS if an existing named event was opened. If a new named event was created, Status will return NO_ERROR. If the second form of the constructor is used, the Status member function will return NO_ERROR if the event was successfully opened.

See Also:

CMclKernel::Wait and CMclKernel::WaitForTwo methods

Win32 CreateEvent and OpenEvent functions

The "Events" section in Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation


CMclEvent::Pulse

Mcl C++ Class Library Reference ›› CMclEvent Class ››

CMclEvent::Pulse

BOOL Pulse( void );

Momentarily sets the event to the signaled state just long enough to unblock any threads that are currently waiting for the event to be signaled. Once waiting threads are released, the event is immediately reset to the nonsignaled state automatically.

Return Values

TRUE

If the operation succeeded

FALSE

If the operation fails

See Also:

CMclKernel::Wait method

CMclKernel::WaitForTwo method

Win32 PulseEvent function

The "Events" section in Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool


CMclEvent::Reset

Mcl C++ Class Library Reference ›› CMclEvent Class ››

CMclEvent::Reset

BOOL Reset( void );

Resets the event to the nonsignaled state.

Return Values

TRUE

If the operation succeeded and the event was reset to the nonsignaled state

FALSE

If the operation fails

Comments

Although this function can be used to reset an auto-reset event, it is typically used only with manual-reset events. Auto-reset events are automatically reset by the operating system.

See Also:

CMclKernel::Wait and CMclKernel::WaitForTwo methods

Win32 ResetEvent function

Created with the Personal Edition of HelpNDoc: Full-featured Help generator


CMclEvent::Set

Mcl C++ Class Library Reference ›› CMclEvent Class ››

CMclEvent::Set

BOOL Set( void );

Sets the event to the signaled state. For auto-reset events, the event will remain signaled until one thread waits on the event, at which point the event will automatically be reset to the nonsignaled state. For manual-reset events, the event will remain in the signaled state until the CMclEvent::Reset member function is called.

Return Values

TRUE

If the operation succeeded and the event was set to the signaled state

FALSE

If the operation fails

See Also:

CMclKernel::Wait and CMclKernel::WaitForTwo methods

CMclEvent::Pulse method

Win32 SetEvent function

Created with the Personal Edition of HelpNDoc: Generate Kindle eBooks with ease


CMclEventAutoPtr Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: iPhone web sites made easy


CMclEventAutoPtr Description

Mcl C++ Class Library Reference ›› CMclEventAutoPtr Class ››

CMclEventAutoPtr [Declaration] [Implementation]

typedef CMclDerivedAutoPtr<CMclThread> CMclEventAutoPtr;

Predefined instantiation of the CMclDerivedAutoPtr class typed for CMclEvent objects.

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator


CMclKernel Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easily create EBooks


CMclKernel Description

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel [Declaration] [Implementation]

class CMclKernel : public CMclWaitableObject

This abstract base class encapsulates the basic functionality of a Win32 kernel object.

CMclKernel Class Members

Public Non-Virtual Methods

GetHandle | Returns the handle to the kernel object
Status | Returns the status of the kernel object
Wait | Waits for the kernel object to be signaled
WaitForTwo | Waits for the given kernel object and another kernel object to become signaled
operator HANDLE | Returns the handle to the kernel object

Public Virtual Methods

~CMclKernel

Class destructor

Protected Non-Virtual Methods

CMclKernel | Class constructor
ThrowError | Error reporting utility function

Protected Data Members

m_dwStatus | Status of the object
m_hHandle | Handle to the Win32 kernel object

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?


CMclKernel::~CMclKernel

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::~CMclKernel

virtual ~CMclKernel() = 0;

Cleans up the wrapper object by closing the handle to the kernel object.

Comments

The class destructor is defined as virtual to ensure that derived class destructors are also virtual. The handle to the kernel object that is stored in CMclKernel::m_hHandle is closed using the Win32 CloseHandle function.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclKernel::CMclKernel

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::CMclKernel

CMclKernel();

Initializes the object wrapper class.

Comments

Initializes the kernel object by setting m_hHandle to NULL and m_dwStatus to ERROR_INVALID_HANDLE. Classes derived from CMclKernel must initialize the CMclKernel::m_hHandle class member variable to a valid Win32 handle before returning from their constructor. Likewise, the CMclKernel::m_dwStatus member variable should be initialized accordingly. If a derived class constructor fails to initialize these member variables, the CMclKernel::ThrowError method should be invoked.

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CMclKernel::GetHandle

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::GetHandle

HANDLE GetHandle(void) const;

Returns the Win32 handle to the kernel object

Comments

The returned handle may be used in any Win32 function that takes a HANDLE parameter except for the CloseHandle function. The CMclKernel class destructor will automatically close the object handle. The handle to the kernel object is stored in the protected m_hHandle member variable.

See Also:

CMclWaitableObject class

Refer to Chapter 3 of Win32 Multithreaded Programming for a discussion on working with handles to kernel objects.

Created with the Personal Edition of HelpNDoc: Free help authoring tool


CMclKernel::m_dwStatus

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::m_dwStatus

DWORD m_dwStatus;

The current status of the kernel object.

Comments

Classes derived from CMclKernel should make sure that this member variable always represents the current state of the object so that threads calling the CMclKernel::GetStatus method will always receive accurate information.

See Also:

CMclKernel::Status method

Win32 GetLastError function

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


CMclKernel::m_hHandle

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::m_hHandle

HANDLE m_hHandle;

The Win32 handle to the kernel object.

Comments

The constructor for classes derived from CMclKernel must initialize this member variable to a valid Win32 kernel object handle before returning. If this cannot be done, the derived class constructor must call the CMclKernel::ThrowError method.

See Also:

CMclKernel::GetHandle function

CMclKernel::operator HANDLE conversion operator

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


CMclKernel::operator HANDLE

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::operator HANDLE

operator HANDLE() const;

Returns the Win32 handle to the kernel object.

Comments

This conversion operator is supplied as a convenience to the programmer. The same rules specified for the GetHandle method apply to the handle returned by this operator.

See Also:

CMclKernel::GetHandle method

Created with the Personal Edition of HelpNDoc: Free Kindle producer


CMclKernel::Status

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::Status

DWORD Status(void) const;

Returns the status of the kernel object that is stored in the m_dwStatus protected member variable.

Comments

Derived classes can control what this method returns by updating the m_dwStatus class member variable.

See Also:

CMclKernel::m_dwStatus member variable

Win32 GetLastError function

Created with the Personal Edition of HelpNDoc: Full-featured Help generator


CMclKernel::ThrowError

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::ThrowError

void ThrowError( DWORD dwStatus );

Optionally throws an error that can be caught using the C++ try/catch construct.

Parameters

dwStatus

Error code to throw

Comments

The operation of this function is controlled by the preprocessor macro __CMCL_THROW_EXCEPTIONS__. If __CMCL_THROW_EXCEPTIONS__ is not defined or is set to TRUE, then this function will use the C++ throw operation to throw a DWORD exception whose value is equal to dwStatus. If __CMCL_THROW_EXCEPTIONS__ is defined to be FALSE, this function does nothing. In the debug build of MCL, this function will print the filename, line number, and value of dwStatus to the debugger using the OutputDebugString function.

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclKernel::Wait

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::Wait

DWORD Wait( DWORD dwMilliseconds );

Blocks the calling thread until the kernel object becomes signaled, or the time-out specified by dwMilliseconds expires.

Returns

When the kernel object is signaled or the time-out specified by dwMilliseconds expires, the function returns any of the following values:

WAIT_OBJECT_0

If the kernel object is signaled

WAIT_ABANDONED_0

If the kernel object is a mutex and the thread owning the mutex exited or was terminated while it owned the mutex

WAIT_TIMEOUT

If the time-out specified by dwMilliseconds expired before the kernel object became signaled

WAIT_FAILED

If the function fails. GetLastError can be called to get more detailed information about the failure.

Parameters

dwMilliseconds

The maximum amount of time, in milliseconds, that the calling thread should be blocked while waiting for the kernel object to become signaled. Specify INFINITE to block indefinitely.

Comments

This function uses the Win32 WaitForSingleObject function to block until the kernel object becomes signaled.

See Also:

CMclKernel::WaitForTwo function

CMclWaitableCollection class

Win32 WaitForSingleObject function

Refer to Chapter 2 of Win32 Multithreaded Programming for a discussion on blocking.

Created with the Personal Edition of HelpNDoc: Write eBooks for the Kindle


CMclKernel::WaitForTwo

Mcl C++ Class Library Reference ›› CMclKernel Class ››

CMclKernel::WaitForTwo

DWORD WaitForTwo( CMclWaitableObject &rCMclWaitableObject, BOOL bWaitAll, DWORD dwMilliseconds );

This function will block the calling thread until one or both of the specified kernel objects become signaled or the time-out specified by dwMilliseconds expires.

Returns

When one or both of the specified kernel objects becomes signaled, or the time-out specified by dwMilliseconds expires, the member function returns one of the following values:

WAIT_OBJECT_0 or (WAIT_OBJECT_0 + 1)

If bWaitAll is TRUE, the return value indicates that both of the kernel objects are signaled. If bWaitAll is FALSE, a return value of WAIT_OBJECT_0 indicates that the object whose WaitForTwo method was called is signaled. A return value of (WAIT_OBJECT_0 + 1) indicates that the object specified by rCMclWaitableObject is signaled.

WAIT_ABANDONED_0 or (WAIT_ABANDONED_0 + 1)

If bWaitAll is TRUE, the return value indicates that one of the kernel objects is signaled and the other kernel object, which must be a mutex, was abandoned by the thread that owned the mutex. If bWaitAll is FALSE, a return value of WAIT_ABANDONDED_0 indicates that the object whose WaitForTwo method was called was a mutex that was abandoned by the thread that owned the mutex. A return value of (WAIT_ABANDONED_0 + 1) indicates that the object specified by rCMclWaitableObject was a mutex that was abandoned by a thread that owned the mutex at the time it exited or was terminated.

WAIT_TIMEOUT

The time-out interval specified by dwMilliseconds elapsed before the conditions specified by bWaitAll were satisfied.

WAIT_FAILED

If the function fails, GetLastError can be called to get more detailed information about the failure.

Parameters

rCMclWaitableObject

A reference to another waitable object that should be waited on in conjunction with this object.

bWaitAll

A flag indicating whether or not one or both of the specified kernel object should be waited on. If TRUE is specified, the calling thread will be blocked until both this object and the object specified by rCMclWaitableObject have become signaled. If FALSE is specified, the calling thread will be blocked until one of the two specified object becomes signaled.

dwMilliseconds

The maximum amount of time, in milliseconds, that the calling thread should be blocked while waiting for the conditions specified by bWaitAll to be satisfied. Specify INFINITE to block indefinitely.

Comments

This function uses the Win32 WaitForMultipleObjects function to block until the conditions specified by bWaitAll are satisfied.

See Also:

CMclKernel::Wait function

CMclWaitableCollection class

Win32 WaitForMultipleObjects function

Refer to Chapter 2 of Win32 Multithreaded Programming for a discussion on blocking.

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation


CMclKernelAutoPtr Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free Kindle producer


CMclKernelAutoPtr Description

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr [Declaration] [Implementation]

class CMclKernelAutoPtr

This class is a base class for all of the Mcl auto-pointer classes. It provides generic auto-pointer functionality for objects derived from CMclKernel. In particular, CMclKernelAutoPtr provides a method of automatically deleting dynamically allocated CMclKernel objects when the auto-pointer is destroyed. This is especially useful for managing arrays of CMclKernel objects, which usually must be dynamically created one element at a time. When an array of auto-pointers goes out of scope, the auto-pointer destructor will delete each CMclKernel object referred to by the auto-pointers in the array.

However, this class does not enforce type safety, and so should not be used directly. The CMclDerivedAutoPtr template class inherits from CMclKernelAutoPtr to enforce type checking.

CMclKernelAutoPtr Class Members

Public Non-Virtual Methods

CMclKernelAutoPtr | Class constructor
operator -> | Pointer dereferencing operator
operator * | Pointer indirection operator
GetHandle | Returns the internal kernel object handle
IsNull | Returns TRUE if the auto-pointer doesn’t refer to any object
Status | Returns the status of an object

Public Virtual Methods

~CMclKernelAutoPtr

Protected Non-Virtual Methods

Reset

Deletes any referred to object and resets the auto-pointer to a null state

Protected Data Members

m_pObjectPtr

Class destructor. Deletes any referred to object.

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator


CMclKernelAutoPtr::~CMclKernelAutoPtr

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::~CMclKernelAutoPtr

virtual ~CMclKernelAutoPtr();

Auto-pointer destructor

Comments

Deletes any object that this auto-pointer is managing and destroys the auto-pointer.

Created with the Personal Edition of HelpNDoc: Easy EBook and documentation generator


CMclKernelAutoPtr::CMclKernelAutoPtr

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::CMclKernelAutoPtr

CMclKernelAutoPtr( CMclKernel *pObjectPtr = NULL );

Auto-pointer constructor

Parameters

pObjectPtr

Optional pointer to a dynamically created CMclKernel object that will be accessed and managed by this auto-pointer.

Created with the Personal Edition of HelpNDoc: Qt Help documentation made easy


CMclKernelAutoPtr::GetHandle

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::GetHandle

HANDLE GetHandle( void ) const;

Returns the internal Win32 HANDLE of the CMclKernel object managed by the auto-pointer.

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


CMclKernelAutoPtr::IsNull

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::IsNull

BOOL IsNull( void ) const;

Tests whether or not the auto-pointer is currently managing an object.

Return Values

TRUE

The auto-pointer is managing an object derived from CMclKernel. The object was assigned to the auto-pointer either in the CMclKernelAutoPtr constructor or in the Reset member function.

FALSE

The auto-pointer is not managing any object.

See Also:

CMclKernerAutoPtr::Reset member function

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


CMclKernelAutoPtr::m_pObjectPtr

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::m_pObjectPtr

CMclKernel *m_pObjectPtr;

This is the member that stores the actual pointer to the managed object.

See Also:

CMclKernerAutoPtr::IsNull member function

CMclKernerAutoPtr::Reset member function

CMclKernelAutoPtr class constructor

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclKernelAutoPtr::operator *

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::operator *

CMclKernel & operator*() const;

Auto-pointer indirection operator

Returns

A reference to the managed object

Comments

This operator allows auto-pointers to use the * operator with a syntax identical to regular pointers.

See Also:

CMclKernelAutoPtr::operator -> member

Created with the Personal Edition of HelpNDoc: Free EPub producer


CMclKernelAutoPtr::operator ->

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::operator ->

CMclKernel * operator->() const;

Auto-pointer dereferencing operator

Returns

A pointer to the managed object, which is then dereferenced by the member name following the operator.

Comments

This operator allows auto-pointers to use the -> operator with a syntax identical to regular pointers.

See Also:

CMclKernelAutoPtr::operator * member

Created with the Personal Edition of HelpNDoc: Free EPub producer


CMclKernelAutoPtr::Reset

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::Reset

void Reset( CMclKernel *pObjectPtr );

Assigns a dynamically created CMclKernel object to be managed by this auto-pointer. Deletes any CMclKernel object previously managed by this auto-pointer.

Parameters

pObjectPtr

A pointer to a dynamically created object derived from CMclKernel, or NULL. Any currently managed object will be deleted. If the parameter is NULL, the currently managed object will be deleted and the auto-pointer reset to the null state. If the parameter refers to the same object as the auto-pointer is already managing, the managed object will not be deleted.

See Also:

CMclKernelAutoPtr::IsNull member function

CMclKernel related classes, methods in this class, data members, etc.

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


CMclKernelAutoPtr::Status

Mcl C++ Class Library Reference ›› CMclKernelAutoPtr Class ››

CMclKernelAutoPtr::Status

DWORD Status( void ) const;

Returns the result of calling the Status member function on the object managed by the auto-pointer.

Created with the Personal Edition of HelpNDoc: Free Kindle producer


CMclLinkedList Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease


CMclLinkedList Description

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList [Declaration and Implementation]

template <class T>
class CMclLinkedList

Parameters

T

The parameter specifies the type of objects which this instantiation of the class will contain in the list. The class must have an accessible assignment operator and copy constructor.

The CMclLinkedList class provides a thread-safe linked list template class that can be instantiated to work with objects of an arbitrary type. Because CMclLinkedList is a template class, each instantiation must be declared to work with a specific type, specified in the parameter T. The linked list class provides operations to insert and remove data objects from the head or tail of the list. The linked list class can be used as is, or additional template classes can be derived which add functionality, such as the CMclStack and CMclQueue classes.

CMclLinkedList Class Members

Public Non-Virtual Methods

CMclLinkedList | Initializes an empty linked list
~CMclLinkedList | Destroys a linked list
GetFromHeadOfList | Retrieves a copy of an object from the front of the list
GetFromTailOfList | Retrieves a copy of an object from the back of the list
PutOnHeadOfList | Adds a copy of an object to the front of the list
PutOnTailOfList | Adds a copy of an object to the back of the list
Status | Returns the constructor creation status

Protected Non-Virtual Methods

AddToFreeList | Adds allocated, unused nodes to the free list
AllocateListNode | Allocates a new list node
Cleanup | Frees all allocated nodes

Protected Data Members

m_cCritSec | Synchronizes list access
m_cNotEmpty | Signaled when the list is not empty
m_dwStatus | Constructor creation status
m_FreeNode | Points to the front node in the free list
m_MasterNode | Points to the front node in the object list

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


CMclLinkedList::~CMclLinkedList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::~CMclLinkedList

~CMclLinkedList();

Deletes any allocated nodes and destroys the list.

Comments

Internally, this destructor calls the Cleanup member function. The list class only stores copies of objects added to the list. Only the copies are deleted, not the original object. For example, if the list was initiated to hold pointers of type char *, only the pointers are deleted, not the memory that they refer to.

See Also:

CMclLinkedList::Cleanup member function

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CMclLinkedList::AddToFreeList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::AddToFreeList

void AddToFreeList( CMclLinkedListNode *pFreeNode );

This method is used to minimize the dynamic allocation of new list nodes.

Parameters

pFreeNode

Pointer to the unused list node to add to the free list.

Comments

This is an internal method used to recycle allocated list nodes when they are removed from the list.

The allocated node is added to a list of free nodes, and the free nodes are then used as needed.

See Also:

CMclLinkedList::AllocateListNode member function

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclLinkedList::AllocateListNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::AllocateListNode

CMclLinkedListNode *AllocateListNode( T & rData );

This method is used to minimize the dynamic allocation of new list nodes.

Returns

A pointer to a node that has had rData copied into it and is ready to be placed into the linked list.

Parameters

rData

Reference to a data object which will be copied into an available list node.

Comments

This is an internal method used to recycle allocated list nodes that are stored in the free list. When an object is placed in the CMclLinkedList, this function will try to get a free node off the free list. If no free nodes are available, it will allocated a new node. In either case, the data object is copied into the free node and returned.

See Also:

CMclLinkedList::AddToFreeList member function

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator


CMclLinkedList::Cleanup

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::Cleanup

void Cleanup( void );

Deletes any allocated nodes and destroys the list.

Comments

The list class only stores copies of objects added to the list. Only the copies are deleted, not the original object. For example, if the list was initiated to hold pointers of type char *, only the pointers are deleted, not the memory that they refer to.

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


CMclLinkedList::CMclLinkedList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::CMclLinkedList

CMclLinkedList();

This constructor initializes an empty list.

Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator


CMclLinkedList::CMclLinkedListDataNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::CMclLinkedListDataNode [Declaration and Implementation]

class CMclLinkedListDataNode : public CMclLinkedListNode

This type of node is used to store the data objects inserted into the linked list. The class implements a functional version of the GetData and SetData operators, which use the copy and assignment operators of the object to be maintained in the list.

CMclLinkedListDataNode Class Members

Public Non-Virtual Methods

CMclLinkedListDataNode

Constructor initializes node internal data storage

Public Virtual Methods

GetData | Retrieves the data stored internally in the node
SetData | Sets the node internal data storage

Public Data Members

m_data

Stores the data element for the node

Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator


CMclLinkedList::CMclLinkedListNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::CMclLinkedListNode [Declaration and Implementation]

class CMclLinkedListNode

This class is used internally by the CMclLinkedList class as a base class for nodes. It defines the basic operations on a node object. A series of node objects properly pointing to each other constitutes the actual linked list for the CMclLinkedList class. The two derived classes, CMclLinkedList::CMclLinkedListSentinalNode and CMclLinkedList::CMclLinkedListDataNode, implement specific node behavior.

CMclLinkedListNode Class Members

Public Virtual Methods

GetData | Retrives the data member for this node
SetData | Sets the data member for this node

Public Data Members

m_pNext | Points to the next node in the linked list
m_pPrev | Points to the previous node in the linked list

Created with the Personal Edition of HelpNDoc: Full-featured EBook editor


CMclLinkedList::CMclLinkedListSentinelNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::CMclLinkedListSentinelNode [Declaration and Implementation]

class CMclLinkedListSentinelNode : public CMclLinkedListNode

This is a class used internally by CMclLinkedList for the special m_MasterNode and m_FreeNode list pointers. It is used to point to the beginning of the internal data node and free node lists. Nodes of this type do not store data, and the SetData and GetData operations are not permitted.

CMclLinkedListSentinelNode Class Members

Public Virtual Methods

GetData | Do not call this method
SetData | Do not call this method

Public Data Members

m_pNext | Points to the first node in the linked list
m_pPrev | Points to the last node in the linked list

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


CMclLinkedList::GetFromHeadOfList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::GetFromHeadOfList

BOOL GetFromHeadOfList( T & rData, DWORD dwTimeout, CMclEvent *pInterrupt = NULL);

Retrieves a copy of the object from the front of the list, with an optional timeout and interrupt event. The object is removed from the list.

Return Values

TRUE

The object was retrieved from the front of the list.

FALSE

The list was empty and no object was placed on the list before the timeout expired or the event became signaled.

Parameters

rData

A reference into which the object at the front of the list will be copied into.

dwTimeout

Milliseconds to wait for an object to appear in the list.

pInterrupt

A pointer to an event object. If this object becomes signaled before the list becomes non-empty, the operation will immediately return FALSE.

See Also:

CMclLinkedList::GetFromTailOfList member function

CMclLinkedList::AddToFreeList member function

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Easily create Help documents


CMclLinkedList::GetFromTailOfList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::GetFromTailOfList

BOOL GetFromTailOfList( T & rData, DWORD dwTimeout, CMclEvent *pInterrupt = NULL);

Retrieves a copy of the object from the back of the list, with an optional timeout and interrupt event. The object is removed from the list.

Return Values

TRUE

The object was retrieved from the back of the list.

FALSE

The list was empty and no object was placed on the list before the timeout expired or the event became signaled.

Parameters

rData

A reference to which the object at the back of the list will be copied.

dwTimeout

Milliseconds to wait for an object to appear in the list.

pInterrupt

A pointer to an event object. If this object becomes signaled before the list becomes non-empty, the operation will immediately return FALSE.

See Also:

CMclLinkedList::GetFromHeadOfList member function

CMclLinkedList::AddToFreeList member function

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


CMclLinkedList::m_cCritSec

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::m_cCritSec

CMclCritSec m_cCritSec;

This critical section member object is used to coordinate operations which examine or modify the internal linked lists. This data member is protected because it is part of the internal implementation of the class and is hidden from users of this class; however, derived classes may need to manipulate m_cCritSec to provide enhanced functionality.

See Also:

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

CMclLinkedList::GetFromHeadOfList member function

CMclLinkedList::GetFromTailOfList member function

CMclLinkedList::PutOnHeadOfList member function

CMclLinkedList::PutOnTailOfList member function

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclLinkedList::m_cNotEmpty

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::m_cNotEmpty

CMclEvent m_cNotEmpty;

This internal manual reset event object is used to signal a thread waiting on a list get operation that data is now available on the list. The event is signaled when the list contains data, and non-signaled when it is empty. This data member is protected because it is part of the internal implementation of the class and is hidden from users of this class; however, derived classes may need to manipulate m_cNotEmpty to provide enhanced functionality.

See Also:

CMclLinkedList::GetFromHeadOfList member function

CMclLinkedList::GetFromTailOfList member function

CMclLinkedList::PutOnHeadOfList member function

CMclLinkedList::PutOnTailOfList member function

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


CMclLinkedList::m_dwStatus

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::m_dwStatus

DWORD m_dwStatus;

This data member contains the status of the constructor. Since a CMclLinkedList object requires several kernel objects to be created in the constructor, any Win32 error codes will be stored here.

See Also:

CMclLinkedList::Status member function

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclLinkedList::m_FreeNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::m_FreeNode

CMclLinkedListSentinelNode m_FreeNode;

The CMclLinkedList class really contains two linked lists: one list of nodes for the actual data in the list, and one for recycling free list nodes. m_FreeNode points to the front and back of the free node list. The m_pNext member points to the front of the list, and m_pPrev points to the back. This dramatically reduces the amount of dynamic memory allocation that the linked lists have to perform. This data member is protected because it is part of the internal implementation of the class and is hidden from users of this class; however, derived classes may need to manipulate m_FreeNode to provide enhanced functionality.

Comments

When a node is on the free list, it still has a copy of a data object in its m_data member. However, this object is not valid. It is essentially a "ghost" of the original object and should not be accessed.

See Also:

CMclLinkedList::m_MasterNode member data

CMclLinkedListNode class documentation

CMclLinkedListSentinelNode class documentation

CMclLinkedDataNode class documentation

Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator


CMclLinkedList::m_MasterNode

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::m_MasterNode

CMclLinkedListSentinelNode m_MasterNode;

The CMclLinkedList class really contains two linked lists: one list of nodes for the actual data in the list, and one for recycling free list nodes. m_MasterNode points to the front and back of the data node list. The m_pNext member points to the front of the list, and m_pPrev points to the back. This dramatically reduces the amount of dynamic memory allocation that linked lists have to perform. This data member is protected because it is part of the internal implementation of the class and is hidden from users of this class; however, derived classes may need to manipulate m_MasterNode to provide enhanced functionality.

See Also:

CMclLinkedList::m_FreeNode member data

CMclLinkedListNode class documentation

CMclLinkedListSentinelNode class documentation

CMclLinkedDataNode class documentation

Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease


CMclLinkedList::PutOnHeadOfList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::PutOnHeadOfList

BOOL PutOnHeadOfList( T & rData );

Places a copy of the rData object on the front of the list.

Return Values

TRUE

The object was copied onto the front of the list.

FALSE

An error occurred. Memory could not be allocated for a new list node.

Parameters

rData

A reference to the data object to be placed on the list.

See Also:

CMclLinkedList::PutOnTailOfList member function

CMclLinkedList::AllocateListNode member function

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Free help authoring tool


CMclLinkedList::PutOnTailOfList

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::PutOnTailOfList

BOOL PutOnTailOfList( T & rData );

Places a copy of the rData object on the back of the list.

Return Values

TRUE

The object was copied onto the back of the list.

FALSE

An error occurred. Memory could not be allocated for a new list node.

Parameters

rData

A reference to the data object to be placed on the list.

See Also:

CMclLinkedList::PutOnHeadOfList member function

CMclLinkedList::AllocateListNode member function

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Produce Kindle eBooks easily


CMclLinkedList::Status

Mcl C++ Class Library Reference ›› CMclLinkedList Class ››

CMclLinkedList::Status

DWORD Status( void ) const;

Return Values

The Win32 error code result of the object constructor. Two kinds of return values are possible:

NO_ERROR

Linked list internal kernel objects were successfully created.

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

Comments

As with all classes in the Mcl library, if exceptions have not been compiled in, it is important to call the Status member function after the constructor completes. Check for NO_ERROR to ensure that the object was initialized successfully.

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CMclLinkedListDataNode Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easily create EPub books


CMclLinkedListDataNode::CMclLinkedListDataNode

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListDataNode::CMclLinkedListDataNode

CMclLinkedListDataNode( T & rData )

This constructor requires a data object to store into the node.

Comments

A data node must always contain an initialized data object.

Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease


CMclLinkedListDataNode::GetData

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListDataNode::GetData

virtual void GetData( T & rData ) = 0;

Copies the object in the node m_data member into the location referenced by rData.

Parameters

rData

Reference to a location in which to copy the node’s data member

Created with the Personal Edition of HelpNDoc: Free help authoring tool


CMclLinkedListDataNode::m_data

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListDataNode::m_data

T m_data;

This is a member variable of the parameterized type of the template class. It is used to store copies of objects inserted into the linked list.

See Also:

CMclLinkedListdataNode::GetData member function

CMclLinkedListdataNode::SetData member function

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents


CMclLinkedListDataNode::SetData

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListDataNode::SetData

virtual void SetData( T & rData ) = 0;

Replaces the node's current data with a copy of the passed-in object.

Parameters

rData

Reference of the object to copy into the data storage for this node.

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


CMclLinkedListNode::GetData

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListNode::GetData

virtual void GetData( T & rData ) = 0;

Copies the node internal data storage into the object referred to by rData.

Parameters

rData

Reference to an object that the node data will be copied into.

Comments

This is a pure virtual function. It must be implemented by derived classes.

Created with the Personal Edition of HelpNDoc: Free help authoring environment


CMclLinkedListNode::m_pNext

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListNode::m_pNext

CMclLinkedListNode *m_pNext;

Pointer to the next node in the linked list.

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclLinkedListNode::m_pPrev

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListNode::m_pPrev

CMclLinkedListNode *m_pPrev;

Pointer to the previous node in the linked list.

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclLinkedListNode::SetData

Mcl C++ Class Library Reference ›› CMclLinkedListDataNode Class ››

CMclLinkedListNode::SetData

virtual void SetData( T & rData ) = 0;

Copies the object referred to by rData into the node internal data storage.

Parameters

rData

Reference to a data object to copy into the node.

Comments

This is a pure virtual function. It must be implemented by derived classes.

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


CMclLinkedListSentinelNode Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free help authoring tool


CMclLinkedListSentinelNode::GetData

Mcl C++ Class Library Reference ›› CMclLinkedListSentinelNode Class ››

CMclLinkedListSentinelNode::GetData

virtual void GetData( T & rData ) = 0;

Throws an exception. Do not call this method.

Comments

This type of node is only to be used for pointing to the front and back of the list. It has been overloaded with this behavior to prevent a program from trying to retrieve data from nodes of this type.

Created with the Personal Edition of HelpNDoc: Free iPhone documentation generator


CMclLinkedListSentinelNode::SetData

Mcl C++ Class Library Reference ›› CMclLinkedListSentinelNode Class ››

CMclLinkedListSentinelNode::SetData

virtual void SetData( T & rData ) = 0;

This method has been overloaded to throw an exception and print debug error messages.

Comments

This type of node is only to be used for pointing to the front and back of the list. It has been overloaded with this behavior to prevent a program from trying to store data in nodes of this type.

See Also:

CMclLinkedList::m_MasterNode member data

CMclLinkedList::m_FreeNode member data

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclMailbox Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


CMclMailbox Description

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox [Declaration] [Implementation]

class CMclMailbox

A mailbox is a named object that contains a fixed number of mail slots of fixed size. It is used to pass messages between threads or processes which have little or no knowledge of each other. Messages are taken out in the same order as they are put in. The clients of the mailbox must agree on a mailbox name, size, and depth, before they can exchange messages asynchronously.

Mailboxes can be written to and read from by each client, including the creator of the mailbox.

A mailbox can be created at the same time that it is opened, or an existing mailbox can be opened, with the attempt to instantiate the CMclMailbox class failing if the mailbox doesn’t already exist.

Each message written to and read from the mailbox is a fixed size. The programmer can implement a structure on top of the raw bytes of the mail slot to transmit information of any format or size up to the total number of bytes available in each mail slot.

CMclMailbox Class Members

Public Non-Virtual Methods

CMclMailbox | Creates or opens a named mailbox
Get | Gets the next message from the mailbox
GetAlertable | Gets the next message from the mailbox alterably
GetProperties | Gets the mailbox slot properties
IsCreator | Returns whether or not this object created the mailbox
Post | Puts a message into the mailbox
PostAlertable | Puts a message into the mailbox alterably
Status | Returns the status of the constructor

Public Virtual Methods

~CMclMailbox

Destroys the mailbox object

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


CMclMailbox::~CMclMailbox

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::~CMclMailbox

virtual ~CMclMailbox();

Destroys the mailbox object. If this is the last mailbox object of this name on the system, the mailbox itself will be removed from the system.

Comments

When all mailbox objects of the same name in the system have been destroyed, the mailbox itself will be deleted from the system. As long as one mailbox object exists, the mailbox will be available on the system for other processes to open and access.

Created with the Personal Edition of HelpNDoc: Full-featured Documentation generator


CMclMailbox::CMclMailbox

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::CMclMailbox

CMclMailbox( DWORD dwMaxDepth, DWORD cbMsgSize, LPCTSTR lpszName = NULL, LPSECURITY_ATTRIBUTES lpMailboxAttributes = NULL );

CMclMailbox( LPCTSTR lpszName );

The first constructor creates a named mailbox with the given depth, message size, and security attributes. If a mailbox of this name already exists on the system, it will be opened. The second constructor will open an existing mailbox of a given name. If the mailbox does not exist, it will not be created.

Parameters

dwMaxDepth

The maximum number of messages the mailbox can hold at one time.

cbMsgSize

The size, in bytes, of an individual mail message.

Comments

It is important that each user of a mailbox agree on the size and number of mail slots in the mailbox. If two clients try to create a mailbox with the same name and different size parameters, the first client will succeed in creating the mailbox and the second client will fail to open the mailbox and receive an ERROR_INVALID_PARAMETER error. Even though each message written and read from the mailbox is a fixed size, the programmer can implement a structure on top of the raw bytes of the mail slot to transmit information of any size up to the total number of bytes available in the mail slot.

As with all classes in the Mcl library, if exceptions have not been compiled in, it is important to call the Status member function after the constructor completes. Check for NO_ERROR or ERROR_ALREADY_EXISTS to ensure that the mailbox was created or opened successfully.

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclMailbox::Get

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::Get

BOOL Get( void *lpMsg, DWORD dwTimeout = INFINITE );

Retrieves the next message in the mailbox with an optional timeout.

Return Values

TRUE

The message was retrieved successfully.

FALSE

Unable to retrieve the message. The timeout expired.

Parameters

lpMsg

A pointer to a buffer equal to the size of the message slot that will be filled with the next message in the mailbox.

dwTimeout

A timeout value that specifies long to wait for a message to be present in the mailbox

Comments

The Get member function copies the oldest message in the mailbox into the buffer passed in the lpMsg parameter. The message is then removed from the mailbox. If no messages are available, the function waits for up to dwTimeout milliseconds for a message to be posted before returning. The message buffer must be the correct mail slot size for the mailbox or access violations may occur.

See Also:

CMclMailbox::GetAltertable method

CMclMailbox::Post method

Created with the Personal Edition of HelpNDoc: Full-featured EPub generator


CMclMailbox::GetAlertable

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::GetAlertable

BOOL GetAlertable( void *lpMsg, CMclEvent *pInterrupt, DWORD dwTimeout = INFINITE );

DWORD GetAlertable( void *lpMsg, const CMclWaitableCollection & rCollection, DWORD dwTimeout = INFINITE );

Retrieves the next message in the mailbox with an optional timeout and interrupt event(s).

Return Values

TRUE

The message was retrieved successfully.

FALSE

Unable to retrieve the message. The timeout expired or an event was signaled before a message became available in the mailbox.

Parameters

lpMsg

A pointer to a buffer equal to the size of the message slot that will be filled with the next message in the mailbox.

dwTimeout

A timeout value for how long to wait for a message to be present in the mailbox.

pInterrupt

A pointer to an event object. If this event is signaled before a slot is available, the GetAlertable function will return immediately without retrieving a message.

rCollection

A reference to a collection of waitable objects. If any object in the collection is signaled before a slot is available, the GetAlertable function will return immediately without retrieving a message.

Comments

The GetAlertable member function copies the oldest message in the mailbox into the buffer passed in the lpMsg parameter. The message is then removed from the mailbox. If no messages are available, the function will wait for up to dwTimeout milliseconds for a message to arrive before returning. GetAlertable will return immediately if pInterrupt or one of the rCollection objects becomes signaled The message buffer must be the correct mail slot size for the mailbox or access violations may occur.

See Also:

CMclMailbox::PostAlertable method

CMclWaitableCollection class documentation

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclMailbox::GetProperties

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::GetProperties

BOOL GetProperties( LPDWORD lpdwDepth, LPDWORD lpcbMsgSize );

Gets the mailbox depth and slot size.

Return Values

TRUE

The mailbox properties were successfully retrieved.

FALSE

An error occurred.

Parameters

lpdwDepth

The maximum number of messages the mailbox can hold at once. That is, the number of mail slots in the mailbox.

lpcbMsgSize

The size, in bytes, of an individual mail message.

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents


CMclMailbox::IsCreator

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::IsCreator

BOOL IsCreator( void );

Return Values

TRUE

This object initially created the mailbox with the name given in the constructor.

FALSE

This object did not create the mailbox with the name given in the constructor. It has opened a mailbox created by another object.

Created with the Personal Edition of HelpNDoc: iPhone web sites made easy


CMclMailbox::Post

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::Post

BOOL Post( const void *lpMsg, DWORD dwTimeout = INFINITE );

Posts a message into the mailbox with an optional timeout.

Return Values

TRUE

The message was posted successfully.

FALSE

Unable to post the message. The timeout expired.

Parameters

lpMsg

A pointer to a buffer equal to the size of the message slot containing the message to post into the mailbox

dwTimeout

A timeout value that determines how long to wait for an available slot

Comments

The Post member function will copy the message passed in the lpMsg parameter to the next available mail slot in the mailbox. If no slots are available, the function will wait for up to dwTimeout milliseconds for a slot to become free before returning. The message must be the correct mail slot size for the mailbox or access violations may occur.

See Also:

CMclMailbox::Get method

CMclMailbox::PostAlertable method

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclMailbox::PostAlertable

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::PostAlertable

BOOL PostAlertable( const void *lpMsg, CMclEvent *pInterrupt, DWORD dwTimeout = INFINITE);

DWORD PostAlertable( const void *lpMsg, const CMclWaitableCollection & rCollection, DWORD dwTimeout = INFINITE);

Puts a message into the mailbox with an optional timeout and interrupt event(s).

Return Values

TRUE

The message was posted successfully.

FALSE

Unable to post the message. The timeout expired or an event was signaled before a free slot was available to post the message into.

Parameters

lpMsg

A pointer to a buffer equal to the size of the message slot containing the message to post into the mailbox.

dwTimeout

A timeout value for how long to wait for an available slot.

pInterrupt

A pointer to an event object. If this event is signaled before a slot is available, the PostAltertable function will return immediately without posting the message.

rCollection

A reference to a collection of waitable objects. If any object in the collection is signaled before a slot is available, the PostAltertable function will return immediately without posting the message.

Comments

The PostAlertable member function copies the message passed in the lpMsg parameter to the next available mail slot in the mailbox. If no slots are available, the function will wait for up to dwTimeout milliseconds for a slot to become free before returning. PostAlertable will return immediately if pInterrupt or one of the rCollection objects becomes signaled. The message must be the correct mail slot size for the mailbox or access violations may occur.

See Also:

CMclMailbox::Post method.

CMclWaitableCollection class documentation.

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclMailbox::Status

Mcl C++ Class Library Reference ›› CMclMailbox Class ››

CMclMailbox::Status

DWORD Status( void ) const;

Return Values

The Win32 error code result of the object constructor:

NO_ERROR

The named mailbox was successfully created or opened.

ERROR_ALREADY_EXISTS

The named mailbox already existed and was opened successfully.

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclMonitor Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclMonitor Description

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor [Declaration] [Implementation]

class CMclMonitor

A monitor is an abstraction of a generic thread synchronization facility. The monitor represents a region in which only one thread is allowed at a time. Multi-thread sensitive functions can be performed safely inside the monitor, which guarantees that only one thread will execute the function at a time.

A thread can request to Enter the monitor, which will block until no thread is in the monitor. A thread can Leave the monitor, which makes the monitor available for another thread to enter. Most powerfully, a thread can request to WaitForCondition, which allows the thread to leave the monitor temporarily, until the monitor is available and a given condition is TRUE.

The monitor is a very general thread synchronization tool which can be applied to many complex thread synchronization problems.

CMclMonitor Class Members

Public Non-Virtual Methods

CMclMonitor | Constructor for the monitor object
Enter | Requests to enter the monitor
Leave | Leaves the monitor
Status | Status of the monitor constructor
WaitForCondition | Temporarily leaves the monitor and re-enters when a condition becomes true

Public Virtual Methods

~CMclMonitor

Monitor object destructor

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclMonitor::~CMclMonitor

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::~CMclMonitor

virtual ~CMclMonitor();

Destructor for the CMclMonitor class.

Comments

The destructor cleans up all internal synchronization objects. It also deletes any internal data structures that are tracking conditions being waited on. However, the CMclCondition objects that are being waited on are not deleted by this destructor.

Created with the Personal Edition of HelpNDoc: Full-featured EBook editor


CMclMonitor::CMclMonitor

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::CMclMonitor

CMclMonitor();

Constructor for the CMclMonitor class.

Comments

Internally, the monitor object constructor creates several synchronization objects. If exceptions are compiled in, an error in this constructor will throw an appropriate exception. If exceptions are not compiled in, you should check the return value of the Status member function before using the monitor.

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


CMclMonitor::Enter

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::Enter

void Enter( void );

Requests to enter the monitor.

Comments

This call will block until the monitor is available -- that is, no other thread is in the monitor. While a thread can re-enter a monitor that it is already in, this is not a good programming practice. Remember to balance requests to Enter the monitor with appropriate calls to Leave the monitor.

See Also:

CMclMonitor::Leave method

CMclMonitor::WaitForCondition method

CMclCondition class documentation

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclMonitor::Leave

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::Leave

void Leave( void );

Causes the calling thread to leave the monitor.

Comments

Leaves the monitor and makes it available for another thread to enter. If any threads are waiting on conditions, leaving the monitor will check those conditions and possibly allow a thread waiting on a condition to reenter the monitor. If no threads are waiting on TRUE conditions, the monitor will be made available for the next thread to call the Enter method or the next thread to WaitForCondition with a TRUE condition expression.

See Also:

CMclMonitor::Enter method

CMclMonitor::WaitForCondition method

CMclCondition class documentation

Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool


CMclMonitor::Status

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::Status

DWORD Status( void );

Return Values

The Win32 error code result of the object constructor:

NO_ERROR

Linked list internal kernel objects were successfully created.

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

Comments

As with all classes in the Mcl library, if exceptions have not been compiled in, is important to call the Status member function after the constructor completes. Check for NO_ERROR to ensure that the object was initialized successfully.

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclMonitor::WaitForCondition

Mcl C++ Class Library Reference ›› CMclMonitor Class ››

CMclMonitor::WaitForCondition

BOOL WaitForCondition( CMclCondition *pcCondition );

Causes a thread to temporarily leave the monitor and block. The thread will be resumed inside the monitor when the given condition evaluates to TRUE. Other threads can Enter the monitor while the calling thread is blocked inside WaitForCondition.

Returns

Description of return value for return values that are not enumerated types of one kind or another.

Return Values

TRUE

The call succeeded. The thread blocked waiting for the condition, and was unblocked when the condition became TRUE. The calling thread is now inside the monitor.

FALSE

The call failed. Memory could not be allowed to track the given condition. The calling thread is still inside the monitor.

Parameters

pcCondition

A pointer to a CMclCondition object that represents the Boolean expression to wait on.

See Also:

CMclMonitor::Enter method

CMclMonitor::Leave method

CMclCondition class documentation

Created with the Personal Edition of HelpNDoc: Qt Help documentation made easy


CMclMutex Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easily create EPub books


CMclMutex Description

Mcl C++ Class Library Reference ›› CMclMutex Class ››

CMclMutex [Declaration] [Implementation]

class CMclMutex : public CMclKernel

The CMclMutex class wraps the Win32 mutex kernel object. Mutexes can be used to synchronize threads that are in the same or different processes. Because the Win32 mutex is a kernel object that can be waited on, CMclMutex is derived from CMclKernel. The CMclKernel::Wait and CMclKernel::WaitForTwo functions can be used to block a thread until the mutex object is signaled and the calling thread can be granted exclusive ownership of the mutex. If more complex wait operations need to be performed, CMclMutex objects can be added to a collection of waitable objects using the CMclWaitableCollection class. The CMclMutex::Release member function is used to release ownership of a mutex. When the CMclMutex object is deleted, the CMclKernel base class destructor will automatically close the handle to the Win32 mutex object.

CMclMutex Class Members

Public Non-Virtual Methods

CMclMutex | Class constructor. Creates or opens a Win32 mutex object.
Release | Releases ownership of an owned mutex.

Created with the Personal Edition of HelpNDoc: Easily create Qt Help files


CMclMutex::CMclMutex

Mcl C++ Class Library Reference ›› CMclMutex Class ››

CMclMutex::CMclMutex

CMclMutex( BOOL bInitialOwner = FALSE, LPCTSTR lpName = NULL, LPSECURITY_ATTRIBUTES lpMutexAttributes = NULL);

CMclMutex( LPCTSTR lpName, BOOL bInheritHandle = FALSE, DWORD dwDesiredAccess = MUTEX_ALL_ACCESS);

The first form of the constructor uses the Win32 CreateMutex function to create a new mutex object. If lpName is NULL, an unnamed mutex that is accessible only to threads within the calling process is created. If lpName is not NULL, and the mutex already exists, it will be opened. The second form of the constructor uses the Win32 OpenMutex function to open an existing named mutex object.

Parameters

bInitialOwner

Specifies whether or not the mutex should be automatically acquired by the calling thread if the mutex is created instead of opened. If TRUE is specified, and the calling thread actually creates the mutex, the mutex will automatically be owned by the calling thread. If TRUE is specified, and the named mutex already exists, the calling thread needs to explicitly use the Wait member function to acquire ownership of the mutex. If FALSE is specified, the calling thread simply creates or opens the mutex without automatically attempting to acquire ownership.

lpName

Optionally specifies the name of a mutex object to create or open. If the first form of the constructor is used, and a mutex by the given name does not already exist, one will be created. If a mutex by this name already exists, a HANDLE to the existing mutex will be retrieved. If the second form of the constructor is used, and a mutex by the given name already exists, it will be opened. If the second form of the constructor is used, and a mutex by the given name does not exist, no mutex will be created. If lpName is NULL, a new unnamed mutex will be created.

lpMutexAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for newly created mutex objects. This parameter may be NULL if the default security attributes for new mutex objects are desired.

bInheritHandle

Indicates whether or not the HANDLE that is returned to an existing mutex object can be inherited by child processes spawned by the calling process.

dwDesiredAccess

A bitmask specifying the type of access the calling thread would like to have to the given named mutex. On Windows NT, the mutex will not be opened if the security descriptor for the given named mutex does not permit the calling process to have the requested access.

Comments

If the first form of the constructor successfully creates the mutex, the Status member function (defined in the CMclKernel base class) will return NO_ERROR. If the first form of the constructor was used but the mutex already existed, the Status member function will return ERROR_ALREADY_EXISTS. If the second form of the constructor is used, and the mutex is successfully opened, Status will return NO_ERROR.

See Also:

The CMclKernel , CMclWaitableObject , and CMclWaitableCollection classes

The CMclKernel::Wait and CMclKernel::WaitForTwo methods

CMclKernel::Status method

The Win32 CreateMutex and OpenMutex functions

The discussion of CreateMutex and OpenMutex in the "Mutexes" section of Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclMutex::Release

Mcl C++ Class Library Reference ›› CMclMutex Class ››

CMclMutex::Release

BOOL Release( void );

Releases ownership of the mutex. This method should only be called if the calling thread has successfully waited for the mutex to become signaled using CMclKernel::Wait or CMclKernel::WaitForTwo .

Return Values

TRUE

If the mutex was succesfully released

FALSE

If the operation failed

Comments

Mutexes are owned objects. This means that once a thread successfully waits for the mutex to become signaled, that thread is the only thread that can release the mutex. Mutexes can be recursively acquired by the owning thread without blocking. If a mutex is acquired multiple times by the same thread, that thread needs to call Release an equal number of times before the mutex will be available for another thread to acquire.

See Also:

The CMclKernel::Wait and CMclKernel::WaitForTwo methods

Win32 ReleaseMutex function

The discussion of ReleaseMutex in the "Mutexes" section of Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: iPhone web sites made easy


CMclMutexAutoPtr

Mcl C++ Class Library Reference ›› CMclMutex Class ››

CMclMutexAutoPtr [Declaration] [Implementation]

typedef CMclDerivedAutoPtr<CMclThread> CMclMutexAutoPtr;

Predefined instantiation of the CMclDerivedAutoPtr class typed for CMclMutex objects

Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator


CMclQueue Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Write EPub books for the iPad


CMclQueue Description

Mcl C++ Class Library Reference ›› CMclQueue Class ››

CMclQueue [Declaration and Implementation]

template <class T>

class CMclQueue : private CMclLinkedList<T>

Parameters

T

Specifies the type of objects that this instantiation of the class will contain in the queue. The class must have an accessible assignment operator and copy constructor.

The CMclQueue class implements a thread-safe queue object with standard first-in, first-out access. It is implemented by privately inheriting all the functionality from CMclLinkedList and providing wrapper functions for adding data to the end of the linked list and retrieving the data from the front.

CMclQueue Class Members

Public Non-Virtual Methods

Get | Takes a data object off the front of the queue
Put | Puts a data object onto the back of the queue
Status | Returns the constructor creation status

Created with the Personal Edition of HelpNDoc: Easy EBook and documentation generator


CMclQueue::Get

Mcl C++ Class Library Reference ›› CMclQueue Class ››

CMclQueue::Get

BOOL Get( T & rData, DWORD dwTimeout = INFINITE, CMclEvent *pInterrupt = NULL );

Retrieves a copy of the object from the front of the list, with an optional timeout and interrupt event. The object is removed from the list.

Return Values

TRUE

The object was retrieved from the front of the list.

FALSE

The list was empty and no object was placed on the list before the timeout expired or the event became signaled.

Parameters

rData

A reference into which the object at the front of the list will be copied.

dwTimeout

Number of milliseconds to wait for an object to appear in the list.

pInterrupt

A pointer to an event object. If this object becomes signaled before the list becomes non-empty, the operation will immediately return FALSE.

See Also:

CMclLinkedList::GetFromHeadOfList member function

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CMclQueue::Put

Mcl C++ Class Library Reference ›› CMclQueue Class ››

CMclQueue::Put

BOOL Put( T & rData );

Places a copy of the rData object on the back of the list.

Return Values

TRUE

The object was copied onto the back of the list.

FALSE

An error occurred. Memory could not be allocated for a new list node.

Parameters

rData

A reference to the data object to be placed on the list.

See Also:

CMclLinkedList::PutOnTailOfList member function

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclQueue::Status

Mcl C++ Class Library Reference ›› CMclQueue Class ››

CMclQueue::Status

DWORD Status( void );

Return Values

The Win32 error code result of the object constructor:

NO_ERROR

Linked list internal kernel objects were successfully created.

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

Comments

As with all classes in the Mcl library, if exceptions have not been compiled in, it is important to call the Status member function after the constructor completes. Check for NO_ERROR to ensure that the object was initialized successfully.

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


CMclSemaphore Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easily create EBooks


CMclSemaphore Description

Mcl C++ Class Library Reference ›› CMclSemaphore Class ››

CMclSemaphore [Declaration] [Implementation]

class CMclSemaphore : public CMclKernel

This class provides a wrapper around the Win32 semaphore kernel object. It is derived from CMclKernel and CMclWaitableObject so that a thread can block until the semaphore is signaled by calling the Wait member function of the CMclKernel base class, or so that an instance of CMclSemaphore can be added to a CMclWaitableCollection object. The CMclSemaphore::Release member function is used to release a semaphore. And as with all of the kernel objects, the base class CMclKernel destructor will automatically call the Win32 CloseHandle function to close the handle to the semaphore.

CMclSemaphore Class Members

Public Non-Virtual Methods

CMclSemaphore | Creates or opens a Win32 semaphore kernel object
Release | Releases the semaphore by increasing its count by a given amount

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclSemaphore::CMclSemaphore

Mcl C++ Class Library Reference ›› CMclSemaphore Class ››

CMclSemaphore::CMclSemaphore

CMclSemaphore( int nInitialCount, int nMaximumCount, LPCTSTR lpName = NULL, LPSECURITY_ATTRIBUTES lpSemaphoreAttributes = NULL);

CMclSemaphore( LPCTSTR lpName, BOOL bInheritHandle = FALSE, DWORD dwDesiredAccess = SEMAPHORE_ALL_ACCESS);

Creates or opens a Win32 semaphore object. If lpName is not NULL, the first form of the constructor will create a new named semaphore or open an existing one by the same name. If lpName is NULL, the first form of the constructor will create a new unnamed semaphore object that can be used by threads within the calling process. The second form of the constructor opens an existing named semaphore object. If a semaphore with the name indicated by lpName does not exist, no semaphore will be opened or created.

Parameters

nInitialCount

Specifies the initial count for a newly created semaphore. A semaphore remains in the signaled state as long as its count is greater than zero.

nMaximumCount

Specifies the maximum count for a newly created semaphore. The CMclSemaphore::Release member function will not be allowed to increase the semaphore’s count beyond this number.

lpName

Specifies the name of a semaphore to create or open. This parameter may be NULL when using the first form of the class constructor. This parameter must be supplied when using the second form of the constructor.

lpSemaphoreAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies access rights to a newly created semaphore. This parameter may be NULL if the default security attributes for a semaphore are desired.

bInheritHandle

Indicates whether or not the handle returned for the semaphore can be inherited by child processes spawned by the calling process. Specify TRUE to make the handle inheritable. Specify FALSE to prevent the handle from being inherited.

dwDesiredAccess

Indicates the desired access the calling thread would like to the semaphore. If the security attributes for an existing semaphore do not allow threads in the calling process to have the specified access, then the semaphore cannot be opened.

Comments

The CMclKernel::Status member function can be called to determine the success or failure of the constructor. If the first form of the constructor is used, the Status function will return ERROR_ALREADY_EXISTS if an existing named semaphore was opened. If a new named semaphore was created, Status will return NO_ERROR. If the second form of the constructor is used, the Status member function will return NO_ERROR if the semaphore was successfully opened.

See Also:

CMclKernel::Wait and CMclKernel::WaitForTwo methods

CMclSemaphore::Release method

Win32 CreateSemaphore and OpenSemaphore functions

The "Semaphores" section in Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclSemaphore::Release

Mcl C++ Class Library Reference ›› CMclSemaphore Class ››

CMclSemaphore::Release

BOOL Release( LONG lReleaseCount, LONG *plPreviousCount = NULL);

Releases a semaphore by increasing its count by lReleaseCount. This function is used to release a semaphore that has been acquired by using the CMclKernel::Wait or CMclKernel::WaitForTwo member functions. If desired, the previous count for the given semaphore can be returned to the caller through the plPreviousCount parameter.

Return Values

TRUE

If the semaphore’s count was successfully increased by the amount specified by lReleaseCount

FALSE

If the operation fails

Parameters

lReleaseCount

Indicates the amount to increase the semaphore's count by. You should only increase a semaphore’s count equal to the number of times you have reduced its count by using the CMclKernel::Wait or CMclKernel::WaitForTwo member functions, each of which reduces a semaphore's count by one.

plPreviousCount

Points to a DWORD that will receive the semaphore's previous count just before the calling thread increases the semaphore count by lReleaseCount. This parameter is optional and may be NULL if this information is not needed. Note that if other threads are operating on the same semaphore, the semaphore’s count may change just after this information is returned to the calling thread.

Comments

Unlike mutexes, semaphores are not considered "owned" objects. Any thread that has a valid handle to a semaphore (any thread that can call this member function) can release a semaphore, which increases its count.

See Also:

CMclMutex class

CMclKernel::Wait and CMclKernel::WaitForTwo methods

Win32 ReleaseSemaphore function

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CMclSemaphoreAutoPtr Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclSemaphoreAutoPtr Description

Mcl C++ Class Library Reference ›› CMclSemaphoreAutoPtr Class ››

CMclSemaphoreAutoPtr [Declaration] [Implementation]

typedef CMclDerivedAutoPtr<CMclSemaphore> CMclSemaphoreAutoPtr;

Predefined instantiation of the CMclDerivedAutoPtr class typed for CMclSemaphore objects.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclSharedMemory Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease


CMclSharedMemory Description

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory [Declaration] [Implementation]

class CMclSharedMemory

This class encapsulates the Win32 facility for sharing regions of memory between processes. Shared memory regions always have a name. Given a name to a region of shared memory, a program can create the region, open an existing region, and get a pointer to the location of the memory in the process’s address space.

The basic CMclSharedMemory class does not provide for thread synchronization or access control. You must provide these facilities yourself by deriving a class from CMclSharedMemory and adding the proper member functions.

CMclSharedMemory Class Members

Public Non-Virtual Methods

CMclSharedMemory | Creates or opens a shared memory region
GetPtr | Gets a pointer to access the shared memory
IsCreator | Indicates whether or not this object created the shared memory region
Status | Gets the status of the create or open constructor

Public Virtual Methods

~CMclSharedMemory

Unmaps the shared memory

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


CMclSharedMemory::~CMclSharedMemory

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory::~CMclSharedMemory

virtual ~CMclSharedMemory();

Destructor for the shared memory object. Unmaps the shared memory from the process’s address space.

Comments

Once the shared memory object has been destroyed, any pointers into the shared memory region are invalid.

See Also:

CMclSharedMemory::GetPtr member function

Created with the Personal Edition of HelpNDoc: Write EPub books for the iPad


CMclSharedMemory::CMclSharedMemory

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory::CMclSharedMemory

CMclSharedMemory( LONG lSize, LPCTSTR lpName, LPSECURITY_ATTRIBUTES lpSharedMemoryAttributes = NULL );

CMclSharedMemory( LPCTSTR lpName );

The first constructor creates a named region of shared memory of the given size and security attributes. If the named region already exists, it will be opened. The second constructor will open an existing shared memory region of a given name. If the named region does not exist, the region will not be created. After using the second constructor, it is important to call the Status member function and check for NO_ERROR to ensure that the shared memory region was opened successfully.

Parameters

lSize

The size of the shared memory region to create. If the named region already exists and lSize is greater than the current size, the shared memory region will be grown to lSize bytes.

lpName

A name for the shared memory region. By using the same name, different processes can access the same region of shared memory.

lpSharedMemoryAttributes

A pointer to the security attributes structure that should be used to create the new shared memory region. By specifying NULL, default security attributes will be used.

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


CMclSharedMemory::GetPtr

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory::GetPtr

void *GetPtr( void );

Returns

A pointer to the region of shared memory. While valid, this pointer can be used like any other pointer in the process address space. The pointer is invalid once the CMclSharedMemory object is destroyed.

See Also:

CMclSharedMemory::~CMclSharedMemory class destructor

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclSharedMemory::IsCreator

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory::IsCreator

BOOL IsCreator( void );

Returns

Whether or not this instance of CMclSharedMemory created, rather than opened, the named region of shared memory.

Return Values

TRUE

This object initially created the region of shared memory with the name given in the constructor.

FALSE

This object did not create the region of shared memory with the name given in the constructor. It has opened a region created by another object.

Comments

It is important to realize that simply checking whether or not an object created the shared memory is not enough to guarantee thread synchronization if that memory needs to be initialized before it is accessed by multiple threads. If specific initialization is required, other mechanisms -- either intrinsic to the client of the shared memory object, or internal to a class derived from shared memory -- need to be provided by the programmer.

Created with the Personal Edition of HelpNDoc: Full-featured EPub generator


CMclSharedMemory::Status

Mcl C++ Class Library Reference ›› CMclSharedMemory Class ››

CMclSharedMemory::Status

DWORD Status( void ) const;

Return Values

The Win32 error code result of the object constructor:

NO_ERROR

The shared memory region was successfully created or opened

ERROR_ALREADY_EXISTS

The shared memory region already existed and was opened successfully

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

As with all classes in the Mcl library, if exceptions have not been compiled in, is important to call the Status member function after the constructor completes. Check for NO_ERROR or ERROR_ALREADY_EXISTS to ensure that the shared memory region was created or opened successfully.

Created with the Personal Edition of HelpNDoc: Produce online help for Qt applications


CMclStack Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease


CMclStack Description

Mcl C++ Class Library Reference ›› CMclStack Class ››

CMclStack [Declaration and Implementation]

template <class T>

class CMclStack : private CMclLinkedList<T>

Parameters

T

Specifies the type of objects that this instantiation of the class will contain in the stack. The class must have an accessible assignment operator and copy constructor.

The CMclStack class implements a thread-safe queue object with standard last-in, first-out access. It is implemented by privately inheriting all the functionality from CMclLinkedList and providing wrapper functions for adding data to the front of the linked list and retrieving the data from the front.

CMclStack Class Members

Public Non-Virtual Methods

Pop | Takes a data object off the front of the queue
Push | Puts a data object onto the front of the queue
Status | Returns the constructor creation status

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclStack::Pop

Mcl C++ Class Library Reference ›› CMclStack Class ››

CMclStack::Pop

BOOL Pop( T & rData, DWORD dwTimeout = INFINITE, CMclEvent *pInterrupt = NULL );

Retrieves a copy of the object from the front of the list, with an optional timeout and interrupt event. The object is removed from the list.

Return Values

TRUE

The object was retrieved from the front of the list.

FALSE

The list was empty and no object was placed on the list before the timeout expired or the event became signaled.

Parameters

rData

A reference into which the object at the front of the list will be copied

dwTimeout

Number of milliseconds to wait for an object to appear in the list

pInterrupt

A pointer to an event object. If this object becomes signaled before the list becomes non-empty, the operation will immediately return FALSE.

See Also:

CMclLinkedList::GetFromHeadOfList member function

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?


CMclStack::Push

Mcl C++ Class Library Reference ›› CMclStack Class ››

CMclStack::Push

BOOL Push( T & rData );

Places a copy of the rData object on the front of the list.

Return Values

TRUE

The object was copied onto the front of the list.

FALSE

An error occurred. Memory could not be allocated for a new list node.

Parameters

rData

A reference to the data object to be placed on the list.

See Also

CMclLinkedList::PutOnHeadOfList member function

Created with the Personal Edition of HelpNDoc: Produce electronic books easily


CMclStack::Status

Mcl C++ Class Library Reference ›› CMclStack Class ››

CMclStack::Status

DWORD Status( void );

Return Values

The Win32 error code result of the object constructor:

NO_ERROR

Linked list internal kernel objects were successfully created.

Other Error Codes

Indicate failure. Consult the Win32 API error code documentation or winerror.h for specific information.

Comments

As with all classes in the Mcl library, if exceptions have not been compiled in, it is important to call the Status member function after the constructor completes. Check for NO_ERROR to ensure that the object was initialized successfully.

Created with the Personal Edition of HelpNDoc: Free help authoring environment


CMclThread Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator


CMclThread Description

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread [Declaration] [Implementation]

class CMclThread : public CMclKernel

This class, in conjunction with the CMclThreadHandler class, encapsulates the functionality of a Win32 thread. The class constructor takes a pointer to a CMclThreadHandler object that will be called in the context of a newly created thread. The virtual ThreadHandlerProc method of the supplied CMclThreadHandler object is responsible for supplying the actual implementation of the new thread entry procedure.

CMclThread Class Members

Public Non-Virtual Methods

CMclThread | Initializes the thread object and starts a new thread executing.
GetExitCode | Returns the exit code for the thread.
GetPriority | Returns the current priority of the thread.
GetThreadId | Returns the unique thread ID of this thread
Resume | Resumes the thread
SetPriority | Adjusts the priority of the thread
Suspend | Suspends the thread
Terminate | Terminates the thread

Protected Data Members

m_pcThreadHandler | Points to the CMclThreadHandler object that is associated with this thread
m_uiThreadID | Contains the unique thread ID of this thread

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclThread::CMclThread

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::CMclThread

CMclThread( CMclThreadHandler *pcThreadHandler, unsigned uInitFlag = 0, LPSECURITY_ATTRIBUTES lpSecurity = NULL, unsigned uStackSize = 0);

Creates a new thread and associates that thread with the CMclThreadHandler object specified by pcThreadHandler.

Parameters

pcThreadHandler

Points to a CMclThreadHandler object whose virtual ThreadHandlerProc method should be invoked in the context of the new thread once it starts executing.

uInitFlag

A flag indicating whether or not the newly created thread should be initially suspended or begin executing immediately. If 0 is specified, the thread begins executing immediately after it is created. If CREATE_SUSPENDED is specified, the new thread will not begin executing until the CMclThread::ResumeThread method is called.

lpSecurity

A pointer to the security attributes that should be used to create the new thread. By specifying NULL, default security attributes will be used.

uStackSize

Specifies the initial size of the stack to commit for the new thread. More space for the stack will be committed as needed while the thread executes, up to a maximum of 1 MB of stack.

Comments

The new thread is created using the _beginthreadex C run-time library function. When the newly created thread begins to execute, the virtual ThreadHandlerProc method of the CMclThreadHandler object specified by pcThreadHandler will be invoked. The new thread will exit when the ThreadHandlerProc function returns.

See Also:

CMclThreadHandler abstract base class

C run-time library _beginthreadex function

Refer to the discussion of threads and the C run-time library in Chapter 3 of Win32 Multithreaded Programming for more detailed information on the _beginthreadex function.

Created with the Personal Edition of HelpNDoc: Produce electronic books easily


CMclThread::GetExitCode

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::GetExitCode

BOOL GetExitCode( DWORD *pdwExitCode );

Retrieves the exit code for the thread.

Returns

An indication of whether or not the exit code for the thread was successfully returned.

Return Values

TRUE

If the exit code for the thread is successfully returned. If it is returned, the DWORD pointed to by pdwExitCode will contain the exit code for the thread.

FALSE

If the operation fails.

Parameters

pdwExitCode

A pointer to a DWORD that will receive the exit code for the thread. A value of STILL_ACTIVE (0x0103) will be returned if the thread has not yet exited or been terminated. If the thread has exited or been terminated, the exit code for the thread is returned.

See Also:

CMclThread::Terminate method

Win32 GetExitCodeThread function

Created with the Personal Edition of HelpNDoc: Free iPhone documentation generator


CMclThread::GetPriority

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::GetPriority

int GetPriority(void);

Returns the current base execution priority for the thread.

Returns

The current base priority of the thread or THREAD_PRIORITY_ERROR_RETURN if this operation fails.

Comments

The base priority of a thread can be modified using the CMclThread::SetPriority method.

See Also:

CMclThread::SetPriority method

Win32 GetThreadPriority function

Refer to Chapter 2 of Win32 Multithreaded Programming for more information on thread and process priorities.

Created with the Personal Edition of HelpNDoc: News and information about help authoring tools and software


CMclThread::GetThreadId

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::GetThreadId

DWORD GetThreadId(void);

Returns the unique system-wide thread ID for the thread.

Comments

Each thread is assigned a system-wide ID when the thread is initially created. Once the thread exits, that thread ID may be reused for another thread. The thread ID that was returned by the _beginthreadex function in the class constructor is stored in the protected m_uiThreadID class member variable.

See Also:

CMclThread class constructor

CMclThread::m_uiThreadID member variable

Created with the Personal Edition of HelpNDoc: Easily create EPub books


CMclThread::m_pcThreadHandler

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::m_pcThreadHandler

CMclThreadHandler *m_pcThreadHandler;

A pointer to the thread handler object that is associated with this thread. The thread handler object is passed to the class constructor.

See Also:

CMclThread class constructor

CMclThreadHandler abstract base class

Created with the Personal Edition of HelpNDoc: Free EPub and documentation generator


CMclThread::m_uiThreadID

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::m_uiThreadID

unsigned int m_uiThreadID;

The unique ID assigned to this thread by the operating system when the thread was created.

See Also:

CMclThread class constructor

CMclThread::GetThreadId method

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclThread::Resume

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::Resume

DWORD Resume(void);

Decrements the thread’s suspend count, resuming it if the new suspend count is zero.

Returns

A value indicating the previous suspend state of the thread.

Comments

This function decrements the suspend count for the thread. When the suspend count reaches zero, the thread can resume execution.

See Also:

CMclThread::Suspend method

Refer to Chapter 2 of Win32 Multithreaded Programming for a discussion on suspending threads and to Chapter 3 for a discussion of Win32 thread control APIs.

Created with the Personal Edition of HelpNDoc: Free help authoring environment


CMclThread::SetPriority

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::SetPriority

BOOL SetPriority( int nPriority );

Adjusts the base execution priority of the thread.

Returns

An indication of whether or not the thread’s base execution priority was successfully adjusted

Return Values

TRUE

If the priority of the thread was successfully changed

FALSE

If the operation failed

Parameters

nPriority

The new priority value for the thread. This may be any one of the following values:

THREAD_PRIORITY_TIME_CRITICAL

THREAD_PRIORITY_HIGHEST

THREAD_PRIORITY_ABOVE_NORMAL

THREAD_PRIORITY_NORMAL

THREAD_PRIORITY_BELOW_NORMAL

THREAD_PRIORITY_LOWEST

THREAD_PRIORITY_IDLE

Comments

This function sets the base priority for the thread relative to the process priority class of the process within which the thread is executing. A thread’s base priority, together with the process priority class of the process within which the thread is executing, determines the execution priority of a thread.

See Also:

CMclThread::GetPriority method

Win32 SetThreadPriority function

Refer to Chapter 2 of Win32 Multithreaded Programming for more information on thread and process priorities.

Created with the Personal Edition of HelpNDoc: Write EPub books for the iPad


CMclThread::Suspend

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::Suspend

DWORD Suspend(void);

Suspends the thread.

Returns

A value indicating the previous suspend state of the thread.

Comments

This function increments the suspend count for the thread. As long as a thread’s suspend count is greater than zero, the thread will not execute.

See Also:

CMclThread::Resume method

Refer to Chapter 2 of Win32 Multithreaded Programming for a discussion on suspending threads and Chapter 3 for a discussion of Win32 thread control APIs.

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation


CMclThread::Terminate

Mcl C++ Class Library Reference ›› CMclThread Class ››

CMclThread::Terminate

BOOL Terminate( DWORD dwExitCode);

Terminates the thread.

Returns

An indication of whether or not the thread was successfully terminated

Return Values

TRUE

If the thread was successfully terminated

FALSE

If the thread could not be terminated. Call GetLastError to retrieve detailed information on the failure.

Parameters

dwExitCode

The exit code to use for the given thread. If the thread is successfully terminated, this value will be stored in the thread kernel object and returned by the CMclThread::GetExitCode method or the Win32 GetExitCodeThread function.

Comments

This function uses the Win32 TerminateThread function to destroy the thread and should be used with care. Threads that are terminated by this function do not have a chance to clean up, and DLLs mapped into the process address space are not notified that the thread is exiting.

See Also:

Win32 TerminateThread function

Refer to Chapter 3 of Win32 Multithreaded Programming for more detailed information on terminating threads.

Created with the Personal Edition of HelpNDoc: Create HTML Help, DOC, PDF and print manuals from 1 single source


CMclThreadAutoPtr Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?


CMclThreadAutoPtr Description

Mcl C++ Class Library Reference ›› CMclThreadAutoPtr Class ››

CMclThreadAutoPtr [Declaration] [Implementation]

typedef CMclDerivedAutoPtr<CMclThread> CMclThreadAutoPtr;

Predefined instantiation of the CMclDerivedAutoPtr class typed for CMclThread objects

Created with the Personal Edition of HelpNDoc: Produce electronic books easily


CMclThreadHandler Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Easy EBook and documentation generator


CMclThreadHandler Description

Mcl C++ Class Library Reference ›› CMclThreadHandler Class ››

CMclThreadHandler [Declaration] [Implementation]

class CMclThreadHandler

CMclThreadHandler is an abstract base class that encapsulates the thread entry procedure for a thread. Threads are created by deriving from CMclThreadHandler and overriding the pure virtual ThreadHandlerProc method and then passing a pointer to the derived thread handler object to the CMclThread class constructor . The relationship of the CMclThreadHandler class to the CMclThread class provides great flexibility in designing your application class hierarchies. Each CMclThread object is associated with one CMclThreadHandler instance. To supply the "body" of a thread, derive a thread handler from CMclThreadHandler and then pass a pointer to an instance of your thread handler to a new CMclThread object.

CMclThreadHandler Class Members

Public Virtual Methods

~CMclThreadHandler | Class destructor.
ThreadHandlerProc | Pure virtual function that is invoked in the context of the newly created thread.

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CMclThreadHandler::~CMclThreadHandler

Mcl C++ Class Library Reference ›› CMclThreadHandler Class ››

CMclThreadHandler::~CMclThreadHandler

virtual ~CMclThreadHandler

Cleans up a thread handler object.

Comments

The destructor has an empty body and serves only as a placeholder to ensure that all derived thread handler objects have a virtual destructor. This function is not invoked in the context of the new thread. It is invoked when you destroy your derived thread handler object using operator delete or when the scope containing a local instance of your derived thread handler is exited.

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


CMclThreadHandler::ThreadHandlerProc

Mcl C++ Class Library Reference ›› CMclThreadHandler Class ››

CMclThreadHandler::ThreadHandlerProc

virtual unsigned ThreadHandlerProc(void) = 0;

The virtual thread start routine for a thread. This function is called in the context of the newly created thread by the CMclThread object.

Returns

The return value of this function will be used as the exit code for the thread.

Comments

Derived thread handlers must override this function to provide an implementation of the thread entry procedure. This function will be called in the context of the newly created thread when it begins executing. The new thread will begin executing when the associated CMclThread object constructor calls _beginthreadex or, if the thread was initially created in the suspended state, when the CMclThread::Resume method is called.

See Also:

CMclThread class

Created with the Personal Edition of HelpNDoc: Free help authoring environment


CMclWaitableCollection Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclWaitableCollection

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection [Declaration] [Implementation]

class CMclWaitableCollection

This class provides a mechanism for waiting for one or all of a set of objects to be waited on that are derived from CMclWaitableObject . The data managed by this class are equivalent to the table of HANDLEs that is passed to the Win32 WaitForMultipleObjects function. Likewise, the Wait operation provided by this class actually performs the call to WaitForMultipleObjects. The usage model for this class is that one or more waitable objects are added to the collection. This includes combining two or more existing collections together. Once the collection has been determined, the Wait method is called to wait for one or all of the waitable objects to become signaled.

None of the member functions of this class affect the reference count for the kernel objects that are added to the collection.

CMclWaitableCollection Class Members

Public Non-Virtual Methods

CMclWaitableCollection | Class constructor
Operator = | Replaces the contents of this collection with the objects from another collection
AddCollection | Adds all the waitable objects in the specified CMclWaitableCollection to the current collection
AddObject | Adds a new HANDLE or CMclWaitableObject object to the collection
GetCount | Returns the number of objects currently in the collection
Wait | Waits for one or all of the objects in the collection to become signaled

Public Virtual Methods

~CMclWaitableCollection

Class destructor

Created with the Personal Edition of HelpNDoc: Write eBooks for the Kindle


CMclWaitableCollection::~CMclWaitableCollection

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::~CMclWaitableCollection

virtual ~CMclWaitableCollection();

Cleans up the collection. This function currently does nothing.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclWaitableCollection::AddCollection

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::AddCollection

BOOL AddCollection( const CMclWaitableCollection& rCollection );

Appends the contents of the specified CMclWaitableCollection to this collection.

Return Values

TRUE

If all of the objects in the collection specified by rCollection were successfully added to the collection.

FALSE

If the operation failed. This operation will fail if the internal HANDLE table already contains a MAXIMUM_WAIT_OBJECTS number of HANDLEs.

Parameters

rCollection

A reference to an existing CMclWaitableCollection.

Comments

A maximum of MAXIMUM_WAIT_OBJECTS (defined in WINNT.H as 64) can be added to a collection. Objects are added to the end of the internal HANDLE table. For example, the first object in rCollection will be added to the current object at the index position returned by the GetCount method at the time AddCollection is called. When you wait for any of the objects in the collection to become signaled using the Wait method, the return value from Wait will indicate which object in the table was signaled.

See Also:

CMclWaitableCollection::GetCount method

CMclWaitableCollection::AddObject method

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator


CMclWaitableCollection::AddObject

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::AddObject

BOOL AddObject( const CMclWaitableObject >SP*pObject );

BOOL AddObject( const CMclWaitableObject& rObject );

BOOL AddObject( const HANDLE hHandle );

This method is used to add an individual object to the collection. Three forms of the constructor are provided for convenience. The first two forms will add another CMclWaitableObject to the collection. The third form of the constructor will add a raw HANDLE to a Win32 kernel object to the collection.

Return Values

TRUE

If the object was successfully added to the collection.

FALSE

If the operation failed. This operation will fail if the internal HANDLE table already contains MAXIMUM_WAIT_OBJECTS number of HANDLEs.

Parameters

pObject

A pointer to an object derived from CMclWaitableObject that should be added to the collection.

rObject

A reference to an object derived from CMclWaitableObject that should be added to the collection.

hHandle

A Win32 HANDLE to a kernel object that should be added to the collection.

Comments

A maximum of MAXIMUM_WAIT_OBJECTS (defined in WINNT.H as 64) can be added to a collection. Objects are added to the end of the internal HANDLE table. For example, the first object added to the collection will be at index 0 in the table. When you wait for any of the objects in the collection to become signaled using the Wait method, the return value from Wait will indicate which object in the table was signaled.

See Also:

CMclWaitableCollection::AddCollection method

CMclWaitableCollection::GetCount method

Created with the Personal Edition of HelpNDoc: Free Web Help generator


CMclWaitableCollection::CMclWaitableCollection

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::CMclWaitableCollection

CMclWaitableCollection();

CMclWaitableCollection( CMclWaitableCollection & rhs );

Initializes the internal array of kernel object HANDLEs. The first form of the constructor initializes the table so that it is empty. The second form of the constructor initializes this object with a copy of the HANDLE table from the CMclWaitableCollection object specified by rhs.

Parameters

rhs

A reference to an existing CMclWaitableCollection that will be used to initialize this collection. The collection being instantiated will be initially constructed so that it has the same HANDLEs in its HANDLE table as the collection specified by rhs.

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclWaitableCollection::GetCount

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::GetCount

LONG GetCount( void ) const;

Returns the number of individual objects currently in the collection.

See Also:

CMclWaitableCollection::AddObject method

CMclWaitableCollection::AddCollection method

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


CMclWaitableCollection::operator =

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::operator =

CMclWaitableCollection& operator = ( CMclWaitableCollection& rhs );

Replaces the contents of the collection with the contents of the existing CMclWaitableCollection specified by rhs. None of the existing objects in the collection will be retained in the internal HANDLE table.

Returns

A reference to the collection object

Parameters

rhs

A reference to an existing CMclWaitableCollection object that should be used to populate this collection.

See Also:

CMclWaitableCollection::AddCollection method

CMclWaitableCollection::AddObject method

Created with the Personal Edition of HelpNDoc: Free help authoring environment


CMclWaitableCollection::Wait

Mcl C++ Class Library Reference ›› CMclWaitableCollection Class ››

CMclWaitableCollection::Wait

DWORD Wait( BOOL bWaitAll, DWORD dwMilliseconds ) const;

Blocks the calling thread until one or all of the kernel objects in the collection become signaled, or until the timeout specified by dwMilliseconds occurs. The Win32 WaitForMultipleObjects function is used to perform the wait.

Returns

An indication of why the calling thread was unblocked and allowed to continue executing. The value returned indicates whether or not the operation failed, timed out while waiting for the conditions specified by bWaitAll to be satisfied, or when the conditions specified by bWaitAll have been successfully satisified. Refer to the discussion of the Win32 WaitForMultipleObjects function in Chapter 4 for a detailed description of the possible return values.

Parameters

bWaitAll

Indicates whether the calling thread should be blocked until any or all of the objects currently in the collection becomes signaled. Specify TRUE to block the calling thread until all of the objects become signaled. Specify FALSE to block the calling thread until any one of the objects in the collection becomes signaled.

dwMilliseconds

Specifies a timeout that should be used. If the condition specified by bWaitAll has not been satisfied before dwMilliseconds milliseconds elapses, this function will return WAIT_TIMEOUT.

See Also:

CMclWaitableCollection::AddCollection method

CMclWaitableCollection::AddObject method

CMclWaitableCollection::GetCount method

Win32 WaitForMultipleObjects function

The discussion of the WaitForMultipleObjects function in Chapter 4 of Win32 Multithreaded Programming

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator


CMclWaitableObject Class

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Full-featured Documentation generator


CMclWaitableObject Description

Mcl C++ Class Library Reference ›› CMclWaitableObject Class ››

CMclWaitableObject [Declaration]

class CMclWaitableObject

This abstract base class represents an object that can be waited on in some fashion. The kernel object base class CMclKernel is derived from this class. This class is separated from the CMclKernel class to allow programmers to define objects that can be waited on that are not derived from kernel objects, but that nevertheless can be waited on because they contain an internal kernel object handle. Because this class is an abstract base class, it cannot be instantiated. Derived classes must provide an implementation for the GetHandle and Status methods.

CMclWaitableObject Class Members

Public Virtual Methods

GetHandle | Returns a kernel object handle that can be waited on
Status | Returns the status of the kernel object whose handle is returned by GetHandle

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?


CMclWaitableObject::GetHandle

Mcl C++ Class Library Reference ›› CMclWaitableObject Class ››

CMclWaitableObject::GetHandle

virtual HANDLE GetHandle(void) const = 0;

Returns a kernel object handle that can be waited on using one of the WaitForXxx family of Win32 functions.

Comments

Derived classes must provide an implementation of this function that returns a valid Win32 kernel object handle that can be passed to any of the WaitForXxx Win32 functions.

Created with the Personal Edition of HelpNDoc: Full-featured EPub generator


CMclWaitableObject::Status

Mcl C++ Class Library Reference ›› CMclWaitableObject Class ››

CMclWaitableObject::Status

virtual DWORD Status(void) const = 0;

Returns the current status of the object.

Comments

An object’s status can be anything returned by the GetLastError function. Derived classes must provide an implementation of this function.

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


Utility Functions

Mcl C++ Class Library Reference ››

Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool


CMclIsValidHandle

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclIsValidHandle [Declaration] [Implementation]

BOOL CMclIsValidHandle( HANDLE hHandle );

This function tests a given HANDLE to a Win32 kernel object to see if it’s a valid handle. Some Win32 functions that return HANDLEs to kernel objects return NULL (0) to indicate a failure, while others return INVALID_HANDLE_VALUE (-1) to indicate failure. This function compares hHandle against both of these values. Using this function eliminates potential bugs that can be caused by incorrectly interpreting the return value of a Win32 function that returns a HANDLE to a kernel object.

Parameters

hHandle

Any HANDLE to any Win32 kernel object

Return Values

TRUE

If the handle is valid

FALSE

If the handle is equal to either NULL or INVALID_HANDLE_VALUE

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclThrowError

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclThrowError [Declaration] [Implementation]

void CMclThrowError( DWORD dwStatus );

This is actually a macro that calls the CMclInternalThrowError function, passing it the filename and line number in the source code where CMclThrowError was called. The debug build of CMclInternalThrowError will print the filename, line number, and the value of dwStatus to the debugger.

What happens next, in both the release and debug builds of MCL, depends on whether or not the __CMCL_THROW_EXCEPTIONS__ preprocessor macro was defined to be TRUE or FALSE when the MCL library was built. By default, __CMCL_THROW_EXCEPTIONS__ is defined to be TRUE, which causes CMclInternalError to use the C++ throw command to raise a software exception whose value is equal to dwStatus. You can use the C++ catch command to catch exceptions raised by CMclThrowError. If __CMCL_THROW_EXCEPTIONS__ is defined to be FALSE, CMclThrowInternalError returns without actually throwing an exception.

Parameters

dwStatus

An error code to print to the debugger (in debug builds) and possibly throw as an exception.

Returns

If __CMCL_THROW_EXCEPTIONS__ is defined to be TRUE, this function will throw a C++ exception and may not return. If __CMCL_THROW_EXCEPTIONS__ is defined to be FALSE, this function returns, but does not return any information.

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclWaitAbandoned

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitAbandoned [Declaration] [Implementation]

BOOL CMclWaitAbandoned( DWORD dwWaitResult, DWORD dwHandleCount );

Like CMclWaitSucceeded , this utility function facilitates testing the return value of a wait operation. This function tests to see if dwWaitResult indicates that a mutex being waited on was abandonded by a thread that owned the mutex. A mutex is considered to be abandoned if the thread owning the mutex exits or is terminated without first releasing ownership of the mutex.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

dwHandleCount

The number of handles that were waited on.

Return Values

TRUE

One of the objects being waited on was a mutex that was abandoned. In this case, dwWaitResult indicates which mutex was abandoned. CMclWaitAbandonedIndex can be used to determine the index of the mutex object that was abandoned.

FALSE

No mutex object was being waited on, or no mutex objects being waited on were abandoned while they were owned by another thread.

Comments

This function will return TRUE if dwWaitResult is greater than or equal to WAIT_ABANDONDED_0 and less than (WAIT_ABANDONDED_0 + dwHandleCount).

See Also:

CMclWaitAbandonedIndex function

CMclWaitSucceeded function

CMclWaitTimeout function

CMclWaitFailed function

CMclWaitSucceededIndex function

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CMclWaitAbandonedIndex

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitAbandonedIndex [Declaration] [Implementation]

DWORD CMclWaitAbandonedIndex( DWORD dwWaitResult );

This utility function returns the index of the mutex object that was abandoned while the calling thread was waiting for it to become signaled.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

Comments

This function should not be called unless the CMclWaitAbandoned function returned TRUE when called with dwWaitResult.

See Also:

CMclWaitAbandoned function

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclWaitFailed

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitFailed [Declaration] [Implementation]

BOOL CMclWaitFailed( DWORD dwWaitResult );

Returns TRUE if dwWaitResult indicates that the wait operation returned to the calling thread because a failure other than a timeout occurred or a mutex was abandoned. If the wait operation returned for any other reason, this function returns FALSE.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

Comments

This function will return TRUE if dwWaitResult is equal to WAIT_FAILED.

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework


CMclWaitSucceeded

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitSucceeded [Declaration] [Implementation]

BOOL CMclWaitSucceeded( DWORD dwWaitResult, DWORD dwHandleCount );

This utility function provides a convenient, and less error-prone, way to interpret the return value of a Win32 WaitForXxx function, the Wait and WaitForTwo methods of the CMclKernel class, or the Wait methods of the CMclWaitableObject and CMclWaitableCollection classes. Because these functions can return a number of different values and ranges of values, depending on how many objects were waited on, whether or not the function timed out, or if the operation failed altogether, interpreting these return values can be tricky.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

dwHandleCount

The number of handles that were waited on.

Return Values

TRUE

Indicates that the wait operation succeeded. In this case, dwWaitResult indicates which object was signaled. CMclWaitSucceededIndex can be used to determine the index of the object that was signaled.

FALSE

Indicates that the wait operation returned, even though one or all of the specified objects were not signaled. This includes a general failure, timing out while waiting, or mutex abandonment. In this case, the CMclWaitTimeout , CMclWaitAbandoned , and CMclWaitFailed functions will tell you what type of failure occurred. If CMclWaitAbandoned returns TRUE, the CMclWaitAbandonedIndex will return the index of the mutex in the collection of kernel objects that was abandoned.

Comments

This function will return TRUE if dwWaitResult is greater than or equal to WAIT_OBJECT_0 and less than (WAIT_OBJECT_0 + dwHandleCount).

See Also:

CMclWaitAbandoned function

CMclWaitAbandonedIndex function

CMclWaitFailed function

CMclWaitSucceededIndex function

CMclWaitTimeout function

Created with the Personal Edition of HelpNDoc: Full-featured multi-format Help generator


CMclWaitSucceededIndex

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitSucceededIndex [Declaration] [Implementation]

DWORD CMclWaitSucceededIndex( DWORD dwWaitResult );

This utility function returns the index of the object that was signaled during a wait operation.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

Comments

This function should not be called unless the CMclWaitSucceeded function returned TRUE when called with dwWaitResult.

See Also:

CMclWaitSucceeded function

Created with the Personal Edition of HelpNDoc: Create cross-platform Qt Help files


CMclWaitTimeout

Mcl C++ Class Library Reference ›› Utility Functions ››

CMclWaitTimeout [Declaration] [Implementation]

BOOL CMclWaitTimeout( DWORD dwWaitResult );

Returns TRUE if dwWaitResult indicates that the wait operation returned to the calling thread because the timeout specified in the wait operation expired before any or all of the objects being waited on were signaled. If the wait operation returned for any other reason, this function returns FALSE.

Parameters

dwWaitResult

The value that was returned by a Wait operation.

Comments

This function will return TRUE if dwWaitResult is equal to WAIT_TIMEOUT.

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?