include/osl/thread.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_OSL_THREAD_H
  25 #define INCLUDED_OSL_THREAD_H
  26
  27 #include "sal/config.h"
  28
  29 #include "osl/time.h"
  30 #include "rtl/textenc.h"
  31 #include "sal/saldllapi.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38     Opaque data type for threads. As with all other osl-handles
  39     you can initialize and/or test it to/for 0.
  40 */
  41 typedef void* oslThread;
  42
  43 /** the function-ptr. representing the threads worker-function.
  44 */
  45 typedef void (SAL_CALL *oslWorkerFunction)(void*);
  46
  47 /** levels of thread-priority
  48     Note that oslThreadPriorityUnknown might be returned
  49     by getPriorityOfThread() (e.g. when it is terminated),
  50     but mustn't be used with setPriority()!
  51 */
  52 typedef enum
  53 {
  54     osl_Thread_PriorityHighest,
  55     osl_Thread_PriorityAboveNormal,
  56     osl_Thread_PriorityNormal,
  57     osl_Thread_PriorityBelowNormal,
  58     osl_Thread_PriorityLowest,
  59     osl_Thread_PriorityUnknown,         /* don't use to set */
  60     osl_Thread_Priority_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  61 } oslThreadPriority;
  62
  63
  64 typedef sal_uInt32 oslThreadIdentifier;
  65
  66 typedef void* oslThreadKey;
  67
  68 /** Create the thread, using the function-ptr pWorker as
  69     its main (worker) function. This function receives in
  70     its void* parameter the value supplied by pThreadData.
  71     Once the OS-structures are initialized,the thread starts
  72     running.
  73
  74     @param pWorker      Thread worker function
  75     @param pThreadData  Thread local data
  76
  77     @return 0 if creation failed, otherwise a handle to the thread
  78 */
  79 SAL_DLLPUBLIC oslThread SAL_CALL osl_createThread(oslWorkerFunction pWorker, void* pThreadData);
  80
  81 /** Create the thread, using the function-ptr pWorker as
  82     its main (worker) function. This function receives in
  83     its void* parameter the value supplied by pThreadData.
  84     The thread will be created, but it won't start running.
  85     To wake-up the thread, use resume().
  86
  87     @param pWorker      Thread worker function
  88     @param pThreadData  Thread local data
  89
  90     @return 0 if creation failed, otherwise a handle to the thread
  91 */
  92 SAL_DLLPUBLIC oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData);
  93
  94 /** Get the identifier for the specified thread or if parameter
  95     Thread is NULL of the current active thread.
  96
  97     @param Thread       Handle to thread for the thread ID
  98
  99     @return identifier of the thread
 100 */
 101 SAL_DLLPUBLIC oslThreadIdentifier SAL_CALL osl_getThreadIdentifier(oslThread Thread);
 102
 103 /** Release the thread handle.
 104     If Thread is NULL, the function won't do anything.
 105     Note that we do not interfere with the actual running of
 106     the thread, we just free up the memory needed by the handle.
 107
 108     @param Thread       Handle to thread to release
 109 */
 110 SAL_DLLPUBLIC void SAL_CALL osl_destroyThread(oslThread Thread);
 111
 112 /** Wake-up a thread that was suspended with suspend() or
 113     createSuspended(). The oslThread must be valid!
 114
 115     @param Thread       Handle to thread to resume
 116 */
 117 SAL_DLLPUBLIC void SAL_CALL osl_resumeThread(oslThread Thread);
 118
 119 /** Suspend the execution of the thread. If you want the thread
 120     to continue, call resume(). The oslThread must be valid!
 121
 122     @param Thread       Handle to thread to suspend
 123 */
 124 SAL_DLLPUBLIC void SAL_CALL osl_suspendThread(oslThread Thread);
 125
 126 /** Changes the threads priority.
 127     The oslThread must be valid!
 128
 129     @param Thread       Handle to thread to which to change priority
 130     @param Priority     Thread priority
 131 */
 132 SAL_DLLPUBLIC void SAL_CALL osl_setThreadPriority(oslThread Thread, oslThreadPriority Priority);
 133
 134 /** Retrieves the threads priority.
 135     Returns oslThreadPriorityUnknown for invalid Thread-argument or
 136     terminated thread. (i.e. the oslThread might be invalid.)
 137
 138     @param Thread       Handle to thread for which the priority is retrieved
 139 */
 140 SAL_DLLPUBLIC oslThreadPriority SAL_CALL osl_getThreadPriority(const oslThread Thread);
 141
 142 /** Returns True if the thread was created and has not terminated yet.
 143     Note that according to this definition a "running" thread might be
 144     suspended! Also returns False is Thread is NULL.
 145
 146     @param Thread       Handle to thread
 147 */
 148 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread);
 149
 150 /** Blocks the calling thread until Thread has terminated.
 151     Returns immediately if Thread is NULL.
 152
 153     @param Thread       Handle to thread to join
 154 */
 155 SAL_DLLPUBLIC void SAL_CALL osl_joinWithThread(oslThread Thread);
 156
 157 /** Suspends the execution of the calling thread for at least the given
 158     time.
 159
 160     @param pDelay       Timeout value to wait
 161 */
 162 SAL_DLLPUBLIC void SAL_CALL osl_waitThread(const TimeValue* pDelay);
 163
 164 /** The requested thread will get terminate the next time
 165     scheduleThread() is called.
 166
 167     @param Thread       Handle to thread to terminate
 168 */
 169 SAL_DLLPUBLIC void SAL_CALL osl_terminateThread(oslThread Thread);
 170
 171 /** Schedules in thread to wait till after time slice of specified
 172     thread. scheduleThread() should be called in the working loop
 173     of the thread, so any other thread could also get the
 174     processor. Returns False if the thread should terminate, so
 175     the thread could free any allocated resources.
 176
 177     @param Thread       Handle to thread to schedule in after
 178 */
 179 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_scheduleThread(oslThread Thread);
 180
 181 /** Offers the rest of the threads time-slice to the OS.
 182     Under POSIX you _need_ to yield(), otherwise, since the
 183     threads are not preempted during execution, NO other thread
 184     (even with higher priority) gets the processor. Control is
 185     only given to another thread if the current thread blocks
 186     or uses yield().
 187 */
 188 SAL_DLLPUBLIC void SAL_CALL osl_yieldThread(void);
 189
 190 /** Attempts to set the name of the current thread.
 191
 192     The name of a thread is usually evaluated for debugging purposes.  Not all
 193     platforms support this.  On Linux, a set thread name can be observed with
 194     "ps -L".  On Windows a thread name set while a debugger is attached can be
 195     observed within the debugger.
 196
 197     @param name  the name of the thread; must not be null; on Linux, only the
 198     first 16 characters are used
 199 */
 200 SAL_DLLPUBLIC void SAL_CALL osl_setThreadName(char const * name);
 201
 202 /* Callback when data stored in a thread key is no longer needed */
 203
 204 typedef void (SAL_CALL *oslThreadKeyCallbackFunction)(void *);
 205
 206 /** Create a key to an associated thread local storage pointer. */
 207 SAL_DLLPUBLIC oslThreadKey SAL_CALL osl_createThreadKey(oslThreadKeyCallbackFunction pCallback);
 208
 209 /** Destroy a key to an associated thread local storage pointer. */
 210 SAL_DLLPUBLIC void SAL_CALL osl_destroyThreadKey(oslThreadKey Key);
 211
 212 /** Get to key associated thread specific data. */
 213 SAL_DLLPUBLIC void* SAL_CALL osl_getThreadKeyData(oslThreadKey Key);
 214
 215 /** Set to key associated thread specific data. */
 216 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setThreadKeyData(oslThreadKey Key, void *pData);
 217
 218 /** Get the current thread local text encoding. */
 219 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL osl_getThreadTextEncoding(void);
 220
 221 /** Set the thread local text encoding.
 222     @return the old text encoding.
 223 */
 224 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL osl_setThreadTextEncoding(rtl_TextEncoding Encoding);
 225
 226 #ifdef __cplusplus
 227 }
 228 #endif
 229
 230 #endif // INCLUDED_OSL_THREAD_H
 231
 232 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */