1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef _OSL_THREAD_H_ 25 #define _OSL_THREAD_H_ 26 27 #include <osl/time.h> 28 29 #ifndef _RTL_TEXTENC_H_ 30 # include <rtl/textenc.h> 31 #endif 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 /* oslThreadKey holds a pointer (the w32 impl returns a PTLS*, the unx impl a 67 * pthread_key_t/index); it MUST be pointer-width or the w32 osl_createThreadKey 68 * pointer is truncated on Win64 (LLP64) → osl_getThreadKeyData derefs a bad 69 * pointer and crashes (first seen: cppu getIdContainer during InitVCL). 70 * sal_uIntPtr == sal_uInt32 on x86 (unchanged) / sal_uInt64 on x64. */ 71 typedef sal_uIntPtr oslThreadKey; 72 73 /** Create the thread, using the function-ptr pWorker as 74 its main (worker) function. This functions receives in 75 its void* parameter the value supplied by pThreadData. 76 Once the OS-structures are initialized,the thread starts 77 running. 78 @return 0 if creation failed, otherwise a handle to the thread 79 */ 80 oslThread SAL_CALL osl_createThread(oslWorkerFunction pWorker, void* pThreadData); 81 82 /** Create the thread, using the function-ptr pWorker as 83 its main (worker) function. This functions receives in 84 its void* parameter the value supplied by pThreadData. 85 The thread will be created, but it won't start running. 86 To wake-up the thread, use resume(). 87 @return 0 if creation failed, otherwise a handle to the thread 88 */ 89 oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData); 90 91 /** Get the identifier for the specified thread or if parameter 92 Thread is NULL of the current active thread. 93 @return identifier of the thread 94 */ 95 oslThreadIdentifier SAL_CALL osl_getThreadIdentifier(oslThread Thread); 96 97 /** Release the thread handle. 98 If Thread is NULL, the function won't do anything. 99 Note that we do not interfere with the actual running of 100 the thread, we just free up the memory needed by the handle. 101 */ 102 void SAL_CALL osl_destroyThread(oslThread Thread); 103 104 /** Wake-up a thread that was suspended with suspend() or 105 createSuspended(). The oslThread must be valid! 106 */ 107 void SAL_CALL osl_resumeThread(oslThread Thread); 108 109 /** Suspend the execution of the thread. If you want the thread 110 to continue, call resume(). The oslThread must be valid! 111 */ 112 void SAL_CALL osl_suspendThread(oslThread Thread); 113 114 /** Changes the threads priority. 115 The oslThread must be valid! 116 */ 117 void SAL_CALL osl_setThreadPriority(oslThread Thread, oslThreadPriority Priority); 118 119 /** Retrieves the threads priority. 120 Returns oslThreadPriorityUnknown for invalid Thread-argument or 121 terminated thread. (I.e.: The oslThread might be invalid.) 122 */ 123 oslThreadPriority SAL_CALL osl_getThreadPriority(const oslThread Thread); 124 125 /** Returns True if the thread was created and has not terminated yet. 126 Note that according to this definition a "running" thread might be 127 suspended! Also returns False is Thread is NULL. 128 */ 129 sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread); 130 131 /** Blocks the calling thread until Thread has terminated. 132 Returns immediately if Thread is NULL. 133 */ 134 void SAL_CALL osl_joinWithThread(oslThread Thread); 135 136 /** Blocks the calling thread at least for the given number 137 of time. 138 */ 139 void SAL_CALL osl_waitThread(const TimeValue* pDelay); 140 141 /** The requested thread will get terminate the next time 142 scheduleThread() is called. 143 */ 144 void SAL_CALL osl_terminateThread(oslThread Thread); 145 146 /** Offers the rest of the threads time-slice to the OS. 147 scheduleThread() should be called in the working loop 148 of the thread, so any other thread could also get the 149 processor. Returns False if the thread should terminate, so 150 the thread could free any allocated resources. 151 */ 152 sal_Bool SAL_CALL osl_scheduleThread(oslThread Thread); 153 154 /** Offers the rest of the threads time-slice to the OS. 155 Under POSIX you _need_ to yield(), otherwise, since the 156 threads are not preempted during execution, NO other thread 157 (even with higher priority) gets the processor. Control is 158 only given to another thread if the current thread blocks 159 or uses yield(). 160 */ 161 void SAL_CALL osl_yieldThread(void); 162 163 /** Attempts to set the name of the current thread. 164 165 The name of a thread is usually evaluated for debugging purposes. Not all 166 platforms support this. On Linux, a set thread name can be observed with 167 "ps -L". On Windows with the Microsoft compiler, a thread name set while a 168 debugger is attached can be observed within the debugger. 169 170 @param name the name of the thread; must not be null; on Linux, only the 171 first 16 characters are used 172 */ 173 void SAL_CALL osl_setThreadName(char const * name); 174 175 /* Callback when data stored in a thread key is no longer needed */ 176 177 typedef void (SAL_CALL *oslThreadKeyCallbackFunction)(void *); 178 179 /** Create a key to an associated thread local storage pointer. */ 180 oslThreadKey SAL_CALL osl_createThreadKey(oslThreadKeyCallbackFunction pCallback); 181 182 /** Destroy a key to an associated thread local storage pointer. */ 183 void SAL_CALL osl_destroyThreadKey(oslThreadKey Key); 184 185 /** Get to key associated thread specific data. */ 186 void* SAL_CALL osl_getThreadKeyData(oslThreadKey Key); 187 188 /** Set to key associated thread specific data. */ 189 sal_Bool SAL_CALL osl_setThreadKeyData(oslThreadKey Key, void *pData); 190 191 /** Get the current thread local text encoding. */ 192 rtl_TextEncoding SAL_CALL osl_getThreadTextEncoding(void); 193 194 /** Set the thread local text encoding. 195 @return the old text encoding. 196 */ 197 rtl_TextEncoding SAL_CALL osl_setThreadTextEncoding(rtl_TextEncoding Encoding); 198 199 #ifdef __cplusplus 200 } 201 #endif 202 203 #endif /* _OSL_THREAD_H_ */ 204