The CIRegion class encapsulates the RT region object; it allows waiting for and releasing control (exclusive access). The CIRegion class is typically used as it is. Regions are available in the RT environment only, because they may affect the priority of a using thread, which would be undesired for the Windows thread.

Class members

Constructor

Destructor

Create

Release

Wait

CIRegion::Constructor

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

CIRegion::Destructor

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

CIRegion::Create

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

Syntax

DWORD CIRegion::Create(
    char * pszName, 
    BOOLEAN bPrioQ
);

Parameters

pszName

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

bPrioQ

Indicates whether threads waiting for control will be queued in priority order (TRUE) or FIFO (FALSE); if omitted, FALSE is used. A region with a priority queue may cause priority inheritance to be applied at execution time. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_MEM

Creating a region 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.

CIRegion::Release

With this call control of the region is released.

Syntax

DWORD CIRegion::Release(void);

Regardless of the object to which you apply this call, it always releases control of the last region that the current thread still holds control of. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_CONTEXT

The thread does not currently control a region.

E_EXIST

The object is not attached.

CIRegion::Wait

This call puts the thread in a sleep state until the region is available, or until a timeout occurs.

Syntax

DWORD CIRegion::Wait(
    DWORD dwTimeout
);

Parameters

dwTimeout

Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER); the only acceptable values are NO_WAIT or WAIT_FOREVER. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_EXIST

The object is not attached.

E_PARAM

dwTimeout is wrong.

E_BUSY

The region is controlled by another thread (NO_WAIT only).

E_CONTEXT

The current thread already controls the region.