thread.h File Reference

#include "sal/config.h"
#include "osl/time.h"
#include "rtl/textenc.h"
#include "sal/saldllapi.h"

Go to the source code of this file.

Typedefs
typedef void *	oslThread
	Opaque data type for threads. More...
typedef void(*	oslWorkerFunction) (void *)
	the function-ptr. More...
typedef sal_uInt32	oslThreadIdentifier
typedef void *	oslThreadKey
typedef void(*	oslThreadKeyCallbackFunction) (void *)

Enumerations
enum	oslThreadPriority {   osl_Thread_PriorityHighest, osl_Thread_PriorityAboveNormal, osl_Thread_PriorityNormal, osl_Thread_PriorityBelowNormal,   osl_Thread_PriorityLowest, osl_Thread_PriorityUnknown, osl_Thread_Priority_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }
	levels of thread-priority Note that oslThreadPriorityUnknown might be returned by getPriorityOfThread() (e.g. More...

Functions
SAL_DLLPUBLIC oslThread	osl_createThread (oslWorkerFunction pWorker, void *pThreadData)
	Create the thread, using the function-ptr pWorker as its main (worker) function. More...
SAL_DLLPUBLIC oslThread	osl_createSuspendedThread (oslWorkerFunction pWorker, void *pThreadData)
	Create the thread, using the function-ptr pWorker as its main (worker) function. More...
SAL_DLLPUBLIC oslThreadIdentifier	osl_getThreadIdentifier (oslThread Thread)
	Get the identifier for the specified thread or if parameter Thread is NULL of the current active thread. More...
SAL_DLLPUBLIC void	osl_destroyThread (oslThread Thread)
	Release the thread handle. More...
SAL_DLLPUBLIC void	osl_resumeThread (oslThread Thread)
	Wake-up a thread that was suspended with suspend() or createSuspended(). More...
SAL_DLLPUBLIC void	osl_suspendThread (oslThread Thread)
	Suspend the execution of the thread. More...
SAL_DLLPUBLIC void	osl_setThreadPriority (oslThread Thread, oslThreadPriority Priority)
	Changes the threads priority. More...
SAL_DLLPUBLIC oslThreadPriority	osl_getThreadPriority (const oslThread Thread)
	Retrieves the threads priority. More...
SAL_DLLPUBLIC sal_Bool	osl_isThreadRunning (const oslThread Thread)
	Returns True if the thread was created and has not terminated yet. More...
SAL_DLLPUBLIC void	osl_joinWithThread (oslThread Thread)
	Blocks the calling thread until Thread has terminated. More...
SAL_DLLPUBLIC void	osl_waitThread (const TimeValue *pDelay)
	Suspends the execution of the calling thread for at least the given time. More...
SAL_DLLPUBLIC void	osl_terminateThread (oslThread Thread)
	The requested thread will get terminate the next time scheduleThread() is called. More...
SAL_DLLPUBLIC sal_Bool	osl_scheduleThread (oslThread Thread)
	Schedules in thread to wait till after time slice of specified thread. More...
SAL_DLLPUBLIC void	osl_yieldThread (void)
	Offers the rest of the threads time-slice to the OS. More...
SAL_DLLPUBLIC void	osl_setThreadName (char const *name)
	Attempts to set the name of the current thread. More...
SAL_DLLPUBLIC oslThreadKey	osl_createThreadKey (oslThreadKeyCallbackFunction pCallback)
	Create a key to an associated thread local storage pointer. More...
SAL_DLLPUBLIC void	osl_destroyThreadKey (oslThreadKey Key)
	Destroy a key to an associated thread local storage pointer. More...
SAL_DLLPUBLIC void *	osl_getThreadKeyData (oslThreadKey Key)
	Get to key associated thread specific data. More...
SAL_DLLPUBLIC sal_Bool	osl_setThreadKeyData (oslThreadKey Key, void *pData)
	Set to key associated thread specific data. More...
SAL_DLLPUBLIC rtl_TextEncoding	osl_getThreadTextEncoding (void)
	Get the current thread local text encoding. More...
SAL_DLLPUBLIC rtl_TextEncoding	osl_setThreadTextEncoding (rtl_TextEncoding Encoding)
	Set the thread local text encoding. More...

Typedef Documentation

oslThread

typedef void* oslThread

Opaque data type for threads.

As with all other osl-handles you can initialize and/or test it to/for 0.

oslThreadIdentifier

typedef sal_uInt32 oslThreadIdentifier

oslThreadKey

typedef void* oslThreadKey

oslThreadKeyCallbackFunction

typedef void( * oslThreadKeyCallbackFunction) (void *)

oslWorkerFunction

typedef void( * oslWorkerFunction) (void *)

the function-ptr.

representing the threads worker-function.

Enumeration Type Documentation

oslThreadPriority

enum oslThreadPriority

levels of thread-priority Note that oslThreadPriorityUnknown might be returned by getPriorityOfThread() (e.g.

when it is terminated), but mustn't be used with setPriority()!

Enumerator
osl_Thread_PriorityHighest
osl_Thread_PriorityAboveNormal
osl_Thread_PriorityNormal
osl_Thread_PriorityBelowNormal
osl_Thread_PriorityLowest
osl_Thread_PriorityUnknown
osl_Thread_Priority_FORCE_EQUAL_SIZE

Function Documentation

osl_createSuspendedThread()

SAL_DLLPUBLIC oslThread osl_createSuspendedThread	(	oslWorkerFunction	pWorker,
		void *	pThreadData
	)

Create the thread, using the function-ptr pWorker as its main (worker) function.

This function receives in its void* parameter the value supplied by pThreadData. The thread will be created, but it won't start running. To wake-up the thread, use resume().

Parameters

pWorker	Thread worker function
pThreadData	Thread local data

Returns

0 if creation failed, otherwise a handle to the thread

osl_createThread()

SAL_DLLPUBLIC oslThread osl_createThread	(	oslWorkerFunction	pWorker,
		void *	pThreadData
	)

Create the thread, using the function-ptr pWorker as its main (worker) function.

This function receives in its void* parameter the value supplied by pThreadData. Once the OS-structures are initialized,the thread starts running.

Parameters

pWorker	Thread worker function
pThreadData	Thread local data

Returns

0 if creation failed, otherwise a handle to the thread

osl_createThreadKey()

SAL_DLLPUBLIC oslThreadKey osl_createThreadKey

(

oslThreadKeyCallbackFunction

pCallback

)

Create a key to an associated thread local storage pointer.

osl_destroyThread()

SAL_DLLPUBLIC void osl_destroyThread

(

oslThread

Thread

)

Release the thread handle.

If Thread is NULL, the function won't do anything. Note that we do not interfere with the actual running of the thread, we just free up the memory needed by the handle.

Parameters

Thread

Handle to thread to release

osl_destroyThreadKey()

SAL_DLLPUBLIC void osl_destroyThreadKey

(

oslThreadKey

Key

)

Destroy a key to an associated thread local storage pointer.

osl_getThreadIdentifier()

SAL_DLLPUBLIC oslThreadIdentifier osl_getThreadIdentifier

(

oslThread

Thread

)

Get the identifier for the specified thread or if parameter Thread is NULL of the current active thread.

Parameters

Thread

Handle to thread for the thread ID

Returns

identifier of the thread

osl_getThreadKeyData()

SAL_DLLPUBLIC void* osl_getThreadKeyData

(

oslThreadKey

Key

)

Get to key associated thread specific data.

osl_getThreadPriority()

SAL_DLLPUBLIC oslThreadPriority osl_getThreadPriority

(

const oslThread

Thread

)

Retrieves the threads priority.

Returns oslThreadPriorityUnknown for invalid Thread-argument or terminated thread. (i.e. the oslThread might be invalid.)

Parameters

Thread

Handle to thread for which the priority is retrieved

osl_getThreadTextEncoding()

SAL_DLLPUBLIC rtl_TextEncoding osl_getThreadTextEncoding

(

void

)

Get the current thread local text encoding.

osl_isThreadRunning()

SAL_DLLPUBLIC sal_Bool osl_isThreadRunning

(

const oslThread

Thread

)

Returns True if the thread was created and has not terminated yet.

Note that according to this definition a "running" thread might be suspended! Also returns False is Thread is NULL.

Parameters

Thread

Handle to thread

osl_joinWithThread()

SAL_DLLPUBLIC void osl_joinWithThread

(

oslThread

Thread

)

Blocks the calling thread until Thread has terminated.

Returns immediately if Thread is NULL.

Parameters

Thread

Handle to thread to join

osl_resumeThread()

SAL_DLLPUBLIC void osl_resumeThread

(

oslThread

Thread

)

Wake-up a thread that was suspended with suspend() or createSuspended().

The oslThread must be valid!

Parameters

Thread

Handle to thread to resume

osl_scheduleThread()

SAL_DLLPUBLIC sal_Bool osl_scheduleThread

(

oslThread

Thread

)

Schedules in thread to wait till after time slice of specified thread.

scheduleThread() should be called in the working loop of the thread, so any other thread could also get the processor. Returns False if the thread should terminate, so the thread could free any allocated resources.

Parameters

Thread

Handle to thread to schedule in after

osl_setThreadKeyData()

SAL_DLLPUBLIC sal_Bool osl_setThreadKeyData	(	oslThreadKey	Key,
		void *	pData
	)

Set to key associated thread specific data.

osl_setThreadName()

SAL_DLLPUBLIC void osl_setThreadName

(

char const *

name

)

Attempts to set the name of the current thread.

The name of a thread is usually evaluated for debugging purposes. Not all platforms support this. On Linux, a set thread name can be observed with "ps -L". On Windows a thread name set while a debugger is attached can be observed within the debugger.

Parameters

name	the name of the thread; must not be null; on Linux, only the first 16 characters are used

osl_setThreadPriority()

SAL_DLLPUBLIC void osl_setThreadPriority	(	oslThread	Thread,
		oslThreadPriority	Priority
	)

Changes the threads priority.

The oslThread must be valid!

Parameters

Thread	Handle to thread to which to change priority
Priority	Thread priority

osl_setThreadTextEncoding()

SAL_DLLPUBLIC rtl_TextEncoding osl_setThreadTextEncoding

(

rtl_TextEncoding

Encoding

)

Set the thread local text encoding.

Returns

the old text encoding.

osl_suspendThread()

SAL_DLLPUBLIC void osl_suspendThread

(

oslThread

Thread

)

Suspend the execution of the thread.

If you want the thread to continue, call resume(). The oslThread must be valid!

Parameters

Thread

Handle to thread to suspend

osl_terminateThread()

SAL_DLLPUBLIC void osl_terminateThread

(

oslThread

Thread

)

The requested thread will get terminate the next time scheduleThread() is called.

Parameters

Thread

Handle to thread to terminate

osl_waitThread()

SAL_DLLPUBLIC void osl_waitThread

(

const TimeValue *

pDelay

)

Suspends the execution of the calling thread for at least the given time.

Parameters

pDelay

Timeout value to wait

osl_yieldThread()

SAL_DLLPUBLIC void osl_yieldThread

(

void

)

Offers the rest of the threads time-slice to the OS.

Under POSIX you need to yield(), otherwise, since the threads are not preempted during execution, NO other thread (even with higher priority) gets the processor. Control is only given to another thread if the current thread blocks or uses yield().