Cheap Threads: ct_create

ct_create_thread

The ct_create_thread function creates a thread and enqueues it for execution.

Prototype:

int ct_create_thread
( 
	Ct_handle * pHandle, 
	int priority,
	void * pData, 
	Ct_step_function step, 
	Ct_destructor destruct
);

Parameters:

pHandle: Pointer to a Ct_handle to be populated by ct_create_thread() as an identifier for the new thread. If you don't need to receive a handle for the new thread, you can pass a null pointer for this parameter..
priority: The priority level assigned to the thread. Its value may range from 0 (the highest priority) to CT_PRIORITY_MAX (the lowest priority). The tutorial describes priorities in more detail.
pData: Pointer to the thread's data, or a null pointer if there is no such data. Typically this pointer will be unique for each thread, so that each thread's data will be private to that thread. However it is possible for two or more threads to share the same data.
step: Pointer to a callback function to be executed whenever the thread runs. Must not be NULL. The function must accept a void pointer as a parameter -- the same pointer passed as pData when the thread was created. It must return an int, either CT_OKAY to indicate success or CT_ERROR to indicate failure.
destruct: Pointer to a callback function to be executed when the thread expires. Unless it is NULL, this pointer must point to a function that accepts a void pointer as a parameter (pData again) and returns void.

Return Value:

CT_OKAY if successful, or CT_ERROR if not.

Discussion:

Use ct_create_thread() to define a thread to the scheduler. The callback functions define its behavior, and the pData pointer may indirectly define its initial state. The thread may also access other data unrelated to pData.

If you supply a non-NULL pointer as the first parameter, ct_create_thread() populates the Ct_handle to which it points. This handle serves as an identifier by which you can send it messages. If you never send any messages to a thread, or if you send it messages only through the subscription or broadcast mechanisms, then you don't need to save a handle to it.

If the requested priority is out of range, ct_create_thread() forces it into range by setting it to zero or CT_PRIORITY_MAX, whichever is closer to the value requested.

After creating the thread, ct_create_thread() enqueues it for execution at the specified priority level. If the thread is supposed to be inactive until it receives a message, call ct_create_sleeping_thread() instead.

Threads may create other threads as needed. However you must create at least one thread before calling ct_schedule(), or the scheduler will have nothing to schedule.

Restrictions:

The ct_create_thread function may be called either before the scheduler starts or while the scheduler is running.

Once the scheduler terminates it is pointless to call ct_create_thread() (unless of course the application is preparing to call ct_schedule() again). Doing so will also leak memory, unless the application calls ct_clear() later.

Home