The CISemaphore class encapsulates the RT semaphore object; it allows sending and receiving units, which may represent any application dependant resource. The CISemaphore class is typically used as it is.

Class members

Constructor

Destructor

Create

Release

Wait

CISemaphore::Constructor

The constructor has no arguments. It creates an unattached object.

CISemaphore::Destructor

If the object is attached, the destructor detaches it; then it destroys the object.

CISemaphore::Create

If the object is already attached, it is first detached. Then this call creates an RT semaphore object and attaches it to the object.

Syntax

DWORD CISemaphore::Create(
    char * pszName, 
    WORD wMax,
    BOOLEAN bPrioQ
);

Parameters

pszName

Specifies a name that, if not empty, is used to catalog the RT object.

wMax

Specifies the maximum number of units that may be held in the semaphore; if omitted, 1 is assumed; a semaphore is always created with zero units.

bPrioQ

Indicates whether threads waiting for units will be queued in priority order (TRUE) or FIFO (FALSE); if omitted, FALSE is used. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_MEM

Creating a semaphore requires more memory than the current process owns.

E_LIMIT

The current process reached its RT object limit, or the object directory is full.

E_SLOT

You cannot create more RT objects because the GDT is full.

E_CONTEXT

The object directory already contains the name being cataloged.

E_PARAM

The name is too long or is improperly formatted.

CISemaphore::Release

With this call one or more units are released to the semaphore.

Syntax

DWORD CISemaphore::Release(
    WORD wUnits
);

Parameters

wUnits

Indicates how many units must be released; if omitted, 1 is assumed. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_EXIST

The object is not attached.

E_LIMIT

The calling thread wants to release more units than the semaphore can hold.

CISemaphore::Wait

This call puts the thread in a sleep state until the requested number of units is available, or until a timeout occurs.

Syntax

DWORD CISemaphore::Wait(
    WORD wUnits, 
    DWORD dwTimeout
);

Parameters

wUnits

Specifies how many units are required; if omitted, 1 is assumed.

dwTimeout

Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER). The result is the number of units remaining in the semaphore, or WAIT_FAILED if an error occurred (use GetLastError to obtain the actual error code).

Status

E_OK

No exceptional conditions occurred.

E_TIME

The requested units were not available during the waiting period.

E_EXIST

he object is not attached.