Multithreading

Macros
#define	SP_THREAD_PRIORITY_TIME_CRITICAL   15
#define	SP_THREAD_PRIORITY_HIGHEST   2
#define	SP_THREAD_PRIORITY_ABOVE_NORMAL   1
#define	SP_THREAD_PRIORITY_NORMAL   0
#define	SP_THREAD_PRIORITY_BELOW_NORMAL   (-1)
#define	SP_THREAD_PRIORITY_LOWEST   (-2)
#define	SP_THREAD_PRIORITY_IDLE   (-15)
#define	SP_EVENT_TIMEOUT_INFINITE   -1
#define	SP_EVENT_WAIT_FAILED   -1
#define	SP_EVENT_WAIT_SIGNALED   0
#define	SP_EVENT_WAIT_TIMEOUT   1
#define	SP_EVENT_WAIT_ABANDONED   2

Typedefs
typedef void(*	spCommandThreadCallback) (spCommandThreadStatus status, long data, void *user_data)

Enumerations
enum	spCommandThreadStatus {   SP_COMMAND_THREAD_STARTED = 0 , SP_COMMAND_THREAD_FINISHED = 1 , SP_COMMAND_THREAD_COMMAND_FINISHED = 2 , SP_COMMAND_THREAD_COMMAND_FAILED = 3 ,   SP_COMMAND_THREAD_COMMAND_WAIT_FAILED = 4 }

Functions
void *	spCreateThread (long stacksize, int priority, spThreadFunc func, void *data)
void	spDestroyThread (void *handle)
void	spExitThread (long status)
void	spYieldThread (void)
long	spWaitThread (void *handle)
spThreadId	spGetThreadId (void *handle)
spThreadId	spGetCurrentThreadId (void)
spBool	spEqThreadId (spThreadId id1, spThreadId id2)
void *	spCreateMutex (const char *name)
void	spDestroyMutex (void *handle)
spBool	spLockMutex (void *handle)
spBool	spUnlockMutex (void *handle)
spBool	spWaitMutex (void *handle)
void *	spCreateEvent (spBool manual_reset, spBool initial_signal)
spBool	spDestroyEvent (void *handle)
int	spWaitEventTimeout (void *handle, long timeout_ms)
spBool	spWaitEvent (void *handle)
spBool	spSetEvent (void *handle)
spBool	spResetEvent (void *handle)
spBool	spPulseEvent (void *handle)
spBool	spCreateCommandThread (const char *command, spCommandThreadCallback func, void *data)

Detailed Description

Macro Definition Documentation

SP_THREAD_PRIORITY_TIME_CRITICAL

#define SP_THREAD_PRIORITY_TIME_CRITICAL   15

Thread priority for really time critical processing (higher than the highest thread priority).

SP_THREAD_PRIORITY_HIGHEST

#define SP_THREAD_PRIORITY_HIGHEST   2

Highest thread priority.

SP_THREAD_PRIORITY_ABOVE_NORMAL

#define SP_THREAD_PRIORITY_ABOVE_NORMAL   1

Thread priority above normal.

SP_THREAD_PRIORITY_NORMAL

#define SP_THREAD_PRIORITY_NORMAL   0

Normal thread priority.

SP_THREAD_PRIORITY_BELOW_NORMAL

#define SP_THREAD_PRIORITY_BELOW_NORMAL   (-1)

Thread priority below normal.

SP_THREAD_PRIORITY_LOWEST

#define SP_THREAD_PRIORITY_LOWEST   (-2)

Lowest thread priority.

SP_THREAD_PRIORITY_IDLE

#define SP_THREAD_PRIORITY_IDLE   (-15)

Thread priority for idle state (lower than the lowest thread priority).

SP_EVENT_TIMEOUT_INFINITE

#define SP_EVENT_TIMEOUT_INFINITE   -1

Infinite timeout for spWaitEventTimeout() .

SP_EVENT_WAIT_FAILED

#define SP_EVENT_WAIT_FAILED   -1

Waiting for the event object failed.

SP_EVENT_WAIT_SIGNALED

#define SP_EVENT_WAIT_SIGNALED   0

The event object signaled.

SP_EVENT_WAIT_TIMEOUT

#define SP_EVENT_WAIT_TIMEOUT   1

Timeout period elapsed.

SP_EVENT_WAIT_ABANDONED

#define SP_EVENT_WAIT_ABANDONED   2

Waiting for the event object is abandoned.

Typedef Documentation

spCommandThreadCallback

typedef void(* spCommandThreadCallback) (spCommandThreadStatus status, long data, void *user_data)

Signature of the callback function for spCreateCommandThread() .

Enumeration Type Documentation

spCommandThreadStatus

enum spCommandThreadStatus

Status of the command thread. This status can be accessed as the 1st argument of spCommandThreadCallback .

Enumerator
SP_COMMAND_THREAD_STARTED	Status when the command thread started. data: 0
SP_COMMAND_THREAD_FINISHED	Status when the command thread finished. data: 0
SP_COMMAND_THREAD_COMMAND_FINISHED	Status when the specified command finished. data: command exit code
SP_COMMAND_THREAD_COMMAND_FAILED	Status when the specified command failed. data: errno
SP_COMMAND_THREAD_COMMAND_WAIT_FAILED	Status when waiting for the specified command failed. data: errno

Function Documentation

spCreateThread()

void * spCreateThread ( long stacksize, int priority, spThreadFunc func, void * data )

extern

Creates a new thread. The created thread must be destroyed by spDestroyThread() .

Examples

simple_thread.c, and thread_test.c.

spDestroyThread()

void spDestroyThread ( void * handle )

extern

Destroys the thread created by spCreateThread() .

spExitThread()

void spExitThread ( long status )

extern

Exits the current thread created by spCreateThread() . The behavior of calling this function from the thread created by a function other than spCreatedThread() is undefined.

spYieldThread()

void spYieldThread ( void )

extern

Yields ownership of the current thread to other threads. This function is valid for environment that can gain only one ownership simultaneously such as Mac OS 9.

Examples

thread_test.c.

spWaitThread()

long spWaitThread ( void * handle )

extern

Waits the thread created by spCreateThread() .

Examples

simple_thread.c, and thread_test.c.

spGetThreadId()

spThreadId spGetThreadId ( void * handle )

extern

Gets the ID of the thread.

spGetCurrentThreadId()

spThreadId spGetCurrentThreadId ( void )

extern

Gets the ID of the current thread.

spEqThreadId()

spBool spEqThreadId ( spThreadId id1, spThreadId id2 )

extern

Check whether two thread IDs are the same.

spCreateMutex()

void * spCreateMutex ( const char * name )

extern

Creates a new mutex object.

Examples

thread_test.c.

spDestroyMutex()

void spDestroyMutex ( void * handle )

extern

Destroyes the mutex object created by spCreateMutex() .

spLockMutex()

spBool spLockMutex ( void * handle )

extern

Gains ownership of the mutex object.

Examples

thread_test.c.

spUnlockMutex()

spBool spUnlockMutex ( void * handle )

extern

Relinquishes ownership of the mutex object.

Examples

thread_test.c.

spWaitMutex()

spBool spWaitMutex ( void * handle )

extern

Waits for access to the mutex object.

spCreateEvent()

void * spCreateEvent ( spBool manual_reset, spBool initial_signal )

extern

Creates a new event object.

spDestroyEvent()

spBool spDestroyEvent ( void * handle )

extern

Destroyes the event object created by spCreateEvent() .

spWaitEventTimeout()

int spWaitEventTimeout ( void * handle, long timeout_ms )

extern

Waits for the event object to be a signaled state.

spWaitEvent()

spBool spWaitEvent ( void * handle )

extern

Waits for the event object to be a signaled state.

spSetEvent()

spBool spSetEvent ( void * handle )

extern

Sets the event object to a signaled state.

spResetEvent()

spBool spResetEvent ( void * handle )

extern

Resets the event object to a nonsignaled state.

spPulseEvent()

spBool spPulseEvent ( void * handle )

extern

Sets the event object to a signaled state, and then promptly resets that to a nonsignaled state.

spCreateCommandThread()

spBool spCreateCommandThread ( const char * command, spCommandThreadCallback func, void * data )

extern

Executes the command in a thread.

Parameters

[in]	command	The null-terminated command executed.
[in]	func	The callback function which has the following signature ( spCommandThreadCallback ): void func(spCommandThreadStatus status, long data, void *user_data);
[in]	data	The user data for the callback function. You can obtain this address as the 3rd argument of the callback function.

Return values

SP_TRUE	Success
SP_FALSE	Failure

Examples

command_thread.c.