1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef _OSL_THREAD_H_ 29 #define _OSL_THREAD_H_ 30 31 #include <osl/time.h> 32 33 #ifndef _RTL_TEXTENC_H_ 34 # include <rtl/textenc.h> 35 #endif 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 Opaque data type for threads. As with all other osl-handles 43 you can initialize and/or test it to/for 0. 44 */ 45 typedef void* oslThread; 46 47 /** the function-ptr. representing the threads worker-function. 48 */ 49 typedef void (SAL_CALL *oslWorkerFunction)(void*); 50 51 /** levels of thread-priority 52 Note that oslThreadPriorityUnknown might be returned 53 by getPriorityOfThread() (e.g. when it is terminated), 54 but mustn't be used with setPriority()! 55 */ 56 typedef enum 57 { 58 osl_Thread_PriorityHighest, 59 osl_Thread_PriorityAboveNormal, 60 osl_Thread_PriorityNormal, 61 osl_Thread_PriorityBelowNormal, 62 osl_Thread_PriorityLowest, 63 osl_Thread_PriorityUnknown, /* don't use to set */ 64 osl_Thread_Priority_FORCE_EQUAL_SIZE = SAL_MAX_ENUM 65 } oslThreadPriority; 66 67 68 typedef sal_uInt32 oslThreadIdentifier; 69 70 typedef sal_uInt32 oslThreadKey; 71 72 /** Create the thread, using the function-ptr pWorker as 73 its main (worker) function. This functions receives in 74 its void* parameter the value supplied by pThreadData. 75 Once the OS-structures are initialized,the thread starts 76 running. 77 @return 0 if creation failed, otherwise a handle to the thread 78 */ 79 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 functions 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 @return 0 if creation failed, otherwise a handle to the thread 87 */ 88 oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData); 89 90 /** Get the identifier for the specified thread or if parameter 91 Thread is NULL of the current active thread. 92 @return identifier of the thread 93 */ 94 oslThreadIdentifier SAL_CALL osl_getThreadIdentifier(oslThread Thread); 95 96 /** Release the thread handle. 97 If Thread is NULL, the function won't do anything. 98 Note that we do not interfere with the actual running of 99 the thread, we just free up the memory needed by the handle. 100 */ 101 void SAL_CALL osl_destroyThread(oslThread Thread); 102 103 /** Wake-up a thread that was suspended with suspend() or 104 createSuspended(). The oslThread must be valid! 105 */ 106 void SAL_CALL osl_resumeThread(oslThread Thread); 107 108 /** Suspend the execution of the thread. If you want the thread 109 to continue, call resume(). The oslThread must be valid! 110 */ 111 void SAL_CALL osl_suspendThread(oslThread Thread); 112 113 /** Changes the threads priority. 114 The oslThread must be valid! 115 */ 116 void SAL_CALL osl_setThreadPriority(oslThread Thread, oslThreadPriority Priority); 117 118 /** Retrieves the threads priority. 119 Returns oslThreadPriorityUnknown for invalid Thread-argument or 120 terminated thread. (I.e.: The oslThread might be invalid.) 121 */ 122 oslThreadPriority SAL_CALL osl_getThreadPriority(const oslThread Thread); 123 124 /** Returns True if the thread was created and has not terminated yet. 125 Note that according to this definition a "running" thread might be 126 suspended! Also returns False is Thread is NULL. 127 */ 128 sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread); 129 130 /** Blocks the calling thread until Thread has terminated. 131 Returns immediately if Thread is NULL. 132 */ 133 void SAL_CALL osl_joinWithThread(oslThread Thread); 134 135 /** Blocks the calling thread at least for the given number 136 of time. 137 */ 138 void SAL_CALL osl_waitThread(const TimeValue* pDelay); 139 140 /** The requested thread will get terminate the next time 141 scheduleThread() is called. 142 */ 143 void SAL_CALL osl_terminateThread(oslThread Thread); 144 145 /** Offers the rest of the threads time-slice to the OS. 146 scheduleThread() should be called in the working loop 147 of the thread, so any other thread could also get the 148 processor. Returns False if the thread should terminate, so 149 the thread could free any allocated resources. 150 */ 151 sal_Bool SAL_CALL osl_scheduleThread(oslThread Thread); 152 153 /** Offers the rest of the threads time-slice to the OS. 154 Under POSIX you _need_ to yield(), otherwise, since the 155 threads are not preempted during execution, NO other thread 156 (even with higher priority) gets the processor. Control is 157 only given to another thread if the current thread blocks 158 or uses yield(). 159 */ 160 void SAL_CALL osl_yieldThread(void); 161 162 /** Attempts to set the name of the current thread. 163 164 The name of a thread is usually evaluated for debugging purposes. Not all 165 platforms support this. On Linux, a set thread name can be observed with 166 "ps -L". On Windows with the Microsoft compiler, a thread name set while a 167 debugger is attached can be observed within the debugger. 168 169 @param name the name of the thread; must not be null; on Linux, only the 170 first 16 characters are used 171 */ 172 void SAL_CALL osl_setThreadName(char const * name); 173 174 /* Callback when data stored in a thread key is no longer needed */ 175 176 typedef void (SAL_CALL *oslThreadKeyCallbackFunction)(void *); 177 178 /** Create a key to an associated thread local storage pointer. */ 179 oslThreadKey SAL_CALL osl_createThreadKey(oslThreadKeyCallbackFunction pCallback); 180 181 /** Destroy a key to an associated thread local storage pointer. */ 182 void SAL_CALL osl_destroyThreadKey(oslThreadKey Key); 183 184 /** Get to key associated thread specific data. */ 185 void* SAL_CALL osl_getThreadKeyData(oslThreadKey Key); 186 187 /** Set to key associated thread specific data. */ 188 sal_Bool SAL_CALL osl_setThreadKeyData(oslThreadKey Key, void *pData); 189 190 /** Get the current thread local text encoding. */ 191 rtl_TextEncoding SAL_CALL osl_getThreadTextEncoding(void); 192 193 /** Set the thread local text encoding. 194 @return the old text encoding. 195 */ 196 rtl_TextEncoding SAL_CALL osl_setThreadTextEncoding(rtl_TextEncoding Encoding); 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif /* _OSL_THREAD_H_ */ 203 204