Cheap Threads: ct_create_sleeping

ct_create_sleeping_thread

The ct_create_sleeping_thread function creates a thread that will be inactive until it receives an event.

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:

The ct_create_sleeping_thread function is exactly like the ct_create_thread function, except that it does not enqueue the new thread for execution. Instead, it puts it in a list of sleeping threads that are waiting on events.

You could get the same effect with ct_create_thread(), provided that the thread put itself to sleep on its first run without doing anything. However, coding for that first-time exception is a nuisance that ct_create_sleeping_thread() enables you to avoid.

Restrictions:

The ct_create_sleeping_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_sleeping_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