A base class for implementing INtime real time threads; the CIThread class exists only in the RT environment.

You can use the thread object in these ways:

Create a new executing thread by deriving a specific class from CIThread, which overrides either or both of the InitInstance and DoForever calls and the Create call is used for it.

It is a way to control an existing thread, which is created somewhere else and the CIThread object is used to control some attributes of the RT thread object.

Class members

Constructor

Destructor

Create

InitInstance

DoForever

ExitInstance

SuspendThread

ResumeThread

GetThreadPriority

SetThreadPriority

Sleep

CIThread::Constructor

The constructor, which has no arguments, creates an unattached object.

CIThread::Destructor

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

CIThread::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 CIThread::Create(
    char * pszName, 
    BYTE byPrio,
    DWORD dwStack, 
    BOOLEAN bGo
);

Parameters

pszName

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

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.

Status

E_OK

No exceptional conditions occurred.

E_MEM

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

E_LIMIT

E_SLOT

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_PARAM

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

E_CONTEXT

The object directory already contains the name being cataloged.

The thread that is created executes code resembling this pattern (typically one or both of Init and DoForever will be overruled):

void ThreadCode()
{
    if (!bGo)
        Suspend();
    if (InitInstance())
        while (DoForever())
            ;
    ExitInstance();
    Detach();
}

CIThread::InitInstance

CIThread::InitInstance is called by the framework at the start of the thread and should never be called explicitly. It may be overruled to do some custom, one-time initialization. CIThread::InitInstance returns TRUE immediately.

Syntax

BOOLEAN CIThread::InitInstance(void);

The result should be TRUE if the thread may continue, or FALSE if the thread should be terminated.

CIThread::DoForever

CIThread::DoForever is called by the framework in the body of the thread until it returns FALSE; it should never be called explicitly. CIThread::DoForever returns FALSE immediately, so it is typically overruled.

Syntax

BOOLEAN CIThread::DoForever(void);

The result indicates if the thread should continue calling DoForever (TRUE) or should terminate (FALSE).

CIThread::ExitInstance

CIThread::ExitInstance is called by the framework before terminating the thread and should never be called explicitly. CIThread::ExitInstance returns zero immediately.

Syntax

int CIThread::ExitInstance(void);

The result is a success indicator (zero means OK), but is currently ignored.

CIThread::Terminate

The thread member variable m_run is cleared which should cause the thread to delete itself. Using Terminate is recommended over using Delete as the latter may cause memory leaks.

Syntax:

BOOLEAN CIThread::Terminate(DWORD timout);

Parameters

timeout is the number of milliseconds to poll for the thread to be gone; if less than 10, no wait is done.

Return Value

The return value is TRUE if the thread has deleted itself within the timeout or FALSE if it did not.

CIThread Member variables:

BOOLEAN m_run;// if FALSE, causes DoForever to exit

CIThread::SuspendThread

This call suspends execution of a thread. It may be called more than once for a given thread (up to 255 times), in which case each call to SuspendThread must be offset by a call to ResumeThread. SuspendThread may also be called by a thread for itself.

Syntax

DWORD CIThread::SuspendThread(void);

The result of this call indicates the success or failure.

Status

E_OK

No exceptional conditions occurred.

E_LIMIT

The suspension depth for the specified thread already reached the maximum of 255.

E_CONTEXT

The thread is an interrupt thread.

E_EXIST

The object is not attached.

CIThread::ResumeThread

This call resumes execution of a thread that is in suspended state. It undoes one level of suspending.

Syntax

DWORD CIThread::ResumeThread(void);

The result of this call indicates the success or failure.

Status

E_OK

No exceptional conditions occurred.

E_CONTEXT

The thread is an interrupt thread.

E_EXIST

The object is not attached.

E_LIMIT

The thread is currently not suspended.

CIThread::GetThreadPriority

Use this call to obtain the priority of a thread.

Syntax

BYTE CIThread::GetThreadPriority(void);

The result is either the priority of the thread (0 - 254) or the value BAD_PRIORITY if an error occurred (use GetLastError to obtain the actual error code).

Status

E_OK

No exceptional conditions occurred.

E_EXIST

The object is not attached.

CIThread::SetThreadPriority

With this call the priority of a thread can be changed; such a change may affect the scheduling of threads.

Syntax

DWORD CIThread:SetThreadPriority(
    BYTE byPrio
);

Parameters

byPrio

This parameter must either be zero (this means the best possible priority in the process) or obey this rule: (max priority of process) <= byPrio < 254. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_LIMIT

byPrio contains a bad value.

E_CONTEXT

The thread is an interrupt thread.

E_EXIST

The object is not attached.

CIThread::Sleep (static)

This call puts the thread in an asleep state for a given period. Since the call is a static call, it can be called with a CIThread object, or with just the class name: CIThread::Sleep(..);

Syntax

DWORD CIThread::Sleep(
    DWORD dwTime
);

Parameters

dwTime

Indicates the number of milliseconds to sleep; it should not be WAIT_FOREVER. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_PARAM

dwTime contains a bad value.