This class is only available in the RT environment. It has been derived from CIThread to ease the creation of a thread that waits for incoming units at a semaphore. It must be used to derive an application specific semaphore thread class, or it can be used directly to control a thread object.

Class members

Constructor

Destructor

Create

DoForever

ExitInstance

OnReceive

Member variables

The following member variable is only available to the members of the class and its derived classes:

CISemaphore  m_Semaphore;

CISemaphoreThread::Constructor

See CIThread::Constructor.

CISemaphoreThread::Destructor

See CIThread::Destructor.

CISemaphoreThread::Create

If the object is already attached, it is first detached. Then this call creates a new active RT thread object and attaches it to the object.

Syntax

DWORD CISemaphoreThread::Create(
    char * pszName,
    char * pszSema, 
    WORD wMax,
    BYTE byPrio, 
    DWORD dwStack, 
    BOOLEAN bGo
);

Parameters

pszName

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

pszSema

Specifies the name for the semaphore object; it must be supplied.

wMax

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

byPrio

Indicates the priority for the new thread and must either be zero (this means the best possible priority in the process) or obey this rule: (max priority of process) <= byPrio < 254.

dwStack

Indicates the number of bytes to be reserved for stack space; it should be a multiple of 4 and at least 2048; if omitted, 4096 is used.

bGo

Indicates whether the thread will execute immediately (TRUE) or will be created in suspended state (FALSE); if omitted, TRUE is used. The result is a status indicating success or failure.

The new thread creates the semaphore and catalogs it. The result is a status indicating success or failure:

Status

E_OK

No exceptional conditions occurred.

E_MEM

The current process cannot create a thread or semaphore as specified with the memory available.

E_LIMIT

Either the calling thread's process already reached its object or thread limit, or byPrio contains a bad value, or the object directory is full.

E_SLOT

You cannot create more RT objects because the GDT's slots are full.

E_PARAM

dwStack contains a value of less than 2048, or either name is too long or is improperly formatted.

E_CONTEXT

The object directory already contains one of the names being cataloged.

For details on the code executed by the new thread, See CIThreadCreate.

CISemaphoreThread::DoForever

See CIThread::DoForever. CISemaphoreThread::DoForever is called by the framework and should never be called explicitly. CISemaphoreThread::DoForever waits for a unit at the semaphore (no timeout), calls the OnReceive member (only after successful receive, see below) and returns a boolean status (TRUE for success, FALSE for failure). When overruling this call, do not include a call to the default call.

CISemaphoreThread::ExitInstance

See CIThread::ExitInstance. CISemaphoreThread::ExitInstance is called by the framework before terminating the thread; it should never be called explicitly. CISemaphoreThread::ExitInstance detaches the semaphore object and then returns 0.

CISemaphoreThread::OnReceive

CISemaphoreThread::OnReceive is called by the framework when a unit has been received sucessfully; it should never be called explicitly. CISemaphoreThread::OnReceive just returns TRUE. When overruling this call, there is no need to call the default call.

Syntax

BOOLEAN CISemaphoreThread::OnReceive(void);

Parameters

None. The result must be TRUE to let the thread continue, FALSE to terminate the thread.