LibreOffice
LibreOffice 24.2 SDK C/C++ API Reference
Typedefs | Enumerations | Functions
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

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
pWorkerThread worker function
pThreadDataThread 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
pWorkerThread worker function
pThreadDataThread 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
ThreadHandle 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
ThreadHandle 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
ThreadHandle 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
ThreadHandle 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
ThreadHandle 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
ThreadHandle 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
ThreadHandle 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
namethe 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
ThreadHandle to thread to which to change priority
PriorityThread 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
ThreadHandle 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
ThreadHandle 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
pDelayTimeout 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().