Plank Thread class

A crossplatform thread implementation. More...

Typedefs
typedef struct PlankThread *	PlankThreadRef
	An opaque reference to the Plank Thread object.
typedef PlankUL	PlankThreadID
	Thread ID.
typedef PlankResult(*	PlankThreadFunction )(PlankThreadRef)
	The Thread run function.
Functions
PlankResult	pl_ThreadSleep (PlankD seconds)
	Sleeps the calling thread.
PlankResult	pl_ThreadYield ()
	Yield the calling thread.
PlankThreadID	pl_ThreadCurrentID ()
	Get the thread ID of the calling thread.
PlankThreadRef	pl_Thread_CreateAndInit ()
	Create and initialise a Plank Thread object and return an oqaque reference to it.
PlankThreadRef	pl_Thread_Create ()
	Create a Plank Thread object and return an oqaque reference to it.
PlankResult	pl_Thread_Init (PlankThreadRef p)
	Initialise a Plank Thread object.
PlankResult	pl_Thread_DeInit (PlankThreadRef p)
	Deinitialise a Plank Thread object.
PlankResult	pl_Thread_Destroy (PlankThreadRef p)
	Destroy a Plank Thread object.
PlankThreadID	pl_Thread_GetID (PlankThreadRef p)
	Get the thread ID.
PlankResult	pl_Thread_SetName (PlankThreadRef p, const char *name)
	Set the name of the thread.
PlankResult	pl_Thread_SetFunction (PlankThreadRef p, PlankThreadFunction function)
	Set the thread run function.
PlankResult	pl_Thread_SetUserData (PlankThreadRef p, PlankP userData)
	Set a user data pointer.
PlankP	pl_Thread_GetUserData (PlankThreadRef p)
	Get the user data pointer.
PlankResult	pl_Thread_Start (PlankThreadRef p)
	Starts the Thread.
PlankResult	pl_Thread_Cancel (PlankThreadRef p)
	Cancels the Thread.
PlankResult	pl_Thread_Wait (PlankThreadRef p)
	Wait for the Thread.
PlankB	pl_Thread_IsRunning (PlankThreadRef p)
	Determines if the Thread is still running.
PlankResult	pl_Thread_SetShouldExit (PlankThreadRef p)
	Signals that the Thread should exit.
PlankB	pl_Thread_GetShouldExit (PlankThreadRef p)
	Checks if the Thread has been asked to exit.

---

Detailed Description

A crossplatform thread implementation.

[example tba]

---

Typedef Documentation

typedef PlankResult(* PlankThreadFunction)(PlankThreadRef)

The Thread run function.

This should have the declaration:

 PlankResult myThreadFunction (PlankThreadRef p);

Your will be passed a reference to the Thread calling your function. In there you should check if your thread should exit regularly. You should return the result PlankResult_OK. E.g.,

 PlankResult myThreadFunction (PlankThreadRef p)
 {
    while (! pl_Thread_GetShouldExit (p))
    {
        //.. do some stuff ..
    }
 
    return PlankResult_OK;
 }

In another Thread you can call pl_Thread_SetShouldExit() to tell your Thread to exit gracefully. E.g.

 ...
 pl_Thread_SetShouldExit (myThreadRef, PLANK_TRUE);
 ...

typedef PlankUL PlankThreadID

Thread ID.

typedef struct PlankThread* PlankThreadRef

An opaque reference to the Plank Thread object.

---

Function Documentation

PlankResult pl_Thread_Cancel

(

PlankThreadRef

p

)

Cancels the Thread.

Ideally you should provide a method of checking the return value of pl_Thread_GetShouldExit() regularly within your Thread run function and return from the function if it signals that the thread should exit.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankThreadRef pl_Thread_Create

(

)

Create a Plank Thread object and return an oqaque reference to it.

Returns:

A Plank Thread object as an opaque reference or PLANK_NULL.

PlankThreadRef pl_Thread_CreateAndInit

(

)

Create and initialise a Plank Thread object and return an oqaque reference to it.

Returns:

A Plank Thread object as an opaque reference or PLANK_NULL.

PlankResult pl_Thread_DeInit

(

PlankThreadRef

p

)

Deinitialise a Plank Thread object.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_Thread_Destroy

(

PlankThreadRef

p

)

Destroy a Plank Thread object.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankThreadID pl_Thread_GetID

(

PlankThreadRef

p

)

Get the thread ID.

Parameters:

p	The Plank Thread object.

Returns:

The thread's ID.

PlankB pl_Thread_GetShouldExit

(

PlankThreadRef

p

)

Checks if the Thread has been asked to exit.

This relies on you checking the return value of this function regularly within your Thread run function and return from the function if it signals that the thread should exit.

Parameters:

p	The Plank Thread object.

Returns:

true if the Thread should exit, otherwise false.

PlankP pl_Thread_GetUserData

(

PlankThreadRef

p

)

Get the user data pointer.

This allows the Thread to access data while it is running.

Parameters:

p	The Plank Thread object.

Returns:

The user data pointer.

PlankResult pl_Thread_Init

(

PlankThreadRef

p

)

Initialise a Plank Thread object.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankB pl_Thread_IsRunning

(

PlankThreadRef

p

)

Determines if the Thread is still running.

Parameters:

p	The Plank Thread object.

Returns:

true if the Thread is still running, otherwise false.

PlankResult pl_Thread_SetFunction	(	PlankThreadRef	p,
		PlankThreadFunction	function
	)

Set the thread run function.

This must be called before pl_Thread_Start().

Parameters:

p	The Plank Thread object.
function	The function to use as the Thread run function.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_Thread_SetName	(	PlankThreadRef	p,
		const char *	name
	)

Set the name of the thread.

Useful for debugging. This must be called before pl_Thread_Start(). Not implemented on all platforms.

PlankResult pl_Thread_SetShouldExit

(

PlankThreadRef

p

)

Signals that the Thread should exit.

This relies on you checking the return value of pl_Thread_GetShouldExit() regularly within your Thread run function and return from the function if it signals that the thread should exit.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_Thread_SetUserData	(	PlankThreadRef	p,
		PlankP	userData
	)

Set a user data pointer.

This allows the Thread to access data via the pointer using pl_Thread_GetUserData() while it is running. This must be called before pl_Thread_Start().

Parameters:

p	The Plank Thread object.
userData	The user data pointer to store.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_Thread_Start

(

PlankThreadRef

p

)

Starts the Thread.

The calls the function set using pl_Thread_SetFunction().

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_Thread_Wait

(

PlankThreadRef

p

)

Wait for the Thread.

Parameters:

p	The Plank Thread object.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankThreadID pl_ThreadCurrentID

(

)

Get the thread ID of the calling thread.

Returns:

The thread's ID.

PlankResult pl_ThreadSleep

(

PlankD

seconds

)

Sleeps the calling thread.

Parameters:

seconds

The duration to sleep in seconds.

Returns:

PlankResult_OK if successful, otherwise an error code.

PlankResult pl_ThreadYield

(

)

Yield the calling thread.

This signals to the operating system that other threads could have some scheduler time.

Returns:

PlankResult_OK if successful, otherwise an error code.