Previous

Next

Function RTKCreateThread

RTKCreateThread creates a thread without multithread run-time system library support. Note that most programs should not use this function but rather RTKRTLCreateThread. Please see section How to Create Threads in the RTKernel-32 Programming Manual for details.

typedef void (__cdecl * RTKThreadFunction)(void * Parameter); 

RTKTaskHandle RTKCreateThread(RTKThreadFunction TaskCode, 
                              unsigned          Priority, 
                              unsigned          StackSize, 
                              unsigned long     Flags, 
                              void *            Parameter, 
                              const char *      Name);

Parameters

TaskCode

A C function with __cdecl calling conventions and a single void * parameter. It contains the code to be executed by the new task. Any number of tasks can be created using the same function. All these tasks would execute the same code, but each would have its own local data. Methods of classes cannot be used for parameter TaskCode. Starting a task with a class method is discussed in Advanced Topics, Starting Objects' Methods as Tasks.

Priority

The base priority of the new task as an integer between RTK_MIN_PRIO (1) and RTK_MAX_PRIO (256). Alternatively, zero may be specified to instruct RTKernel-32 to use the default priority given in RTKConfig.DefaultPriority. If this value also is zero, the new task is created with the same base priority as the creating task. The higher the priority, the higher is the urgency of the task.

StackSize

The net stack required by the new task in bytes. RTKernel-32 adds the value RTKConfig.TaskStackOverhead to the value specified and allocates a memory block of corresponding size. If parameter StackSize is zero, RTKConfig.DefaultStackSize is used instead.

Flags

This parameter can be used to select options for the new task. The following values are currently defined:

If neither TF_MATH_CONTEXT nor TF_NO_MATH_CONTEXT are given, RTKernel-32 will set up a floating point context if RF_FPCONTEXT is set in RTKConfig.Flags.

Parameter

This value is passed to the task's function. RTKernel-32 does not interpret this value; it is just passed on. You can use it to pass arbitrary information to the new task.

Name

A pointer to the name of the task. The name of the new task is only used for easy identification of the task and should not be longer than 15 characters. RTKernel-32 just copies the pointer to the name. Therefore, the name should not be modified after the task has been created.

return value

The function value returned to the caller is an RTKernel-32 task handle (not a Win32 handle). It is a reference to the newly created task.

RTKernel-32 distinguishes between the base priority and the execution priority of a task. For scheduling purposes, only the execution priority is considered. The execution priority of a task is the maximum of its base priority and the priorities of all resource or mutex semaphores occupied by the task. The priority of a resource or mutex semaphore is the highest priority of all tasks waiting at the semaphore.

Stack overflows are one of the most common and most evasive errors of multitasking programs. During program development, use functions RTKGetTaskStack, RTKGetMinStack, and RTKTaskInfo extensively to analyze actual stack usage of your tasks. At least during the program development phase, stacks should be dimensioned generously (at least 16k).

In addition to the stack, RTKernel-32 allocates a TCB (Task Control Block, used by RTKernel-32 internally) and - if required - a buffer for the floating point context. If RTKernel-32 is unable to allocate sufficient memory through its memory driver, the program is aborted with a corresponding error message.

Function RTKRTLCreateThread