LibreOffice: osl/thread.h File Reference

LibreOffice LibreOffice 25.8 SDK C/C++ API Reference

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

## 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().