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 | #ifndef INCLUDED_OSL_THREAD_H |
21 | #define INCLUDED_OSL_THREAD_H |
22 | |
23 | #include <sal/config.h> |
24 | |
25 | #include <osl/time.h> |
26 | #include <rtl/textenc.h> |
27 | #include <sal/saldllapi.h> |
28 | |
29 | #ifdef __cplusplus |
30 | extern "C" { |
31 | #endif |
32 | |
33 | /** |
34 | Opaque data type for threads. As with all other osl-handles |
35 | you can initialize and/or test it to/for 0. |
36 | */ |
37 | typedef void* oslThread; |
38 | |
39 | /** the function-ptr. representing the threads worker-function. |
40 | */ |
41 | typedef void (SAL_CALL *oslWorkerFunction)(void*); |
42 | |
43 | /** levels of thread-priority |
44 | Note that oslThreadPriorityUnknown might be returned |
45 | by getPriorityOfThread() (e.g. when it is terminated), |
46 | but mustn't be used with setPriority()! |
47 | */ |
48 | typedef enum |
49 | { |
50 | osl_Thread_PriorityHighest, |
51 | osl_Thread_PriorityAboveNormal, |
52 | osl_Thread_PriorityNormal, |
53 | osl_Thread_PriorityBelowNormal, |
54 | osl_Thread_PriorityLowest, |
55 | osl_Thread_PriorityUnknown, /* don't use to set */ |
56 | osl_Thread_Priority_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
57 | } oslThreadPriority; |
58 | |
59 | |
60 | typedef sal_uInt32 oslThreadIdentifier; |
61 | |
62 | typedef void* oslThreadKey; |
63 | |
64 | /** Create the thread, using the function-ptr pWorker as |
65 | its main (worker) function. This functions receives in |
66 | its void* parameter the value supplied by pThreadData. |
67 | Once the OS-structures are initialized,the thread starts |
68 | running. |
69 | @return 0 if creation failed, otherwise a handle to the thread |
70 | */ |
71 | SAL_DLLPUBLIC oslThread SAL_CALL osl_createThread(oslWorkerFunction pWorker, void* pThreadData); |
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 | The thread will be created, but it won't start running. |
77 | To wake-up the thread, use resume(). |
78 | @return 0 if creation failed, otherwise a handle to the thread |
79 | */ |
80 | SAL_DLLPUBLIC oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData); |
81 | |
82 | /** Get the identifier for the specified thread or if parameter |
83 | Thread is NULL of the current active thread. |
84 | @return identifier of the thread |
85 | */ |
86 | SAL_DLLPUBLIC oslThreadIdentifier SAL_CALL osl_getThreadIdentifier(oslThread Thread); |
87 | |
88 | /** Release the thread handle. |
89 | If Thread is NULL, the function won't do anything. |
90 | Note that we do not interfere with the actual running of |
91 | the thread, we just free up the memory needed by the handle. |
92 | */ |
93 | SAL_DLLPUBLIC void SAL_CALL osl_destroyThread(oslThread Thread); |
94 | |
95 | /** Wake-up a thread that was suspended with suspend() or |
96 | createSuspended(). The oslThread must be valid! |
97 | */ |
98 | SAL_DLLPUBLIC void SAL_CALL osl_resumeThread(oslThread Thread); |
99 | |
100 | /** Suspend the execution of the thread. If you want the thread |
101 | to continue, call resume(). The oslThread must be valid! |
102 | */ |
103 | SAL_DLLPUBLIC void SAL_CALL osl_suspendThread(oslThread Thread); |
104 | |
105 | /** Changes the threads priority. |
106 | The oslThread must be valid! |
107 | */ |
108 | SAL_DLLPUBLIC void SAL_CALL osl_setThreadPriority(oslThread Thread, oslThreadPriority Priority); |
109 | |
110 | /** Retrieves the threads priority. |
111 | Returns oslThreadPriorityUnknown for invalid Thread-argument or |
112 | terminated thread. (I.e.: The oslThread might be invalid.) |
113 | */ |
114 | SAL_DLLPUBLIC oslThreadPriority SAL_CALL osl_getThreadPriority(const oslThread Thread); |
115 | |
116 | /** Returns True if the thread was created and has not terminated yet. |
117 | Note that according to this definition a "running" thread might be |
118 | suspended! Also returns False is Thread is NULL. |
119 | */ |
120 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread); |
121 | |
122 | /** Blocks the calling thread until Thread has terminated. |
123 | Returns immediately if Thread is NULL. |
124 | */ |
125 | SAL_DLLPUBLIC void SAL_CALL osl_joinWithThread(oslThread Thread); |
126 | |
127 | /** Blocks the calling thread at least for the given number |
128 | of time. |
129 | */ |
130 | SAL_DLLPUBLIC void SAL_CALL osl_waitThread(const TimeValue* pDelay); |
131 | |
132 | /** The requested thread will get terminate the next time |
133 | scheduleThread() is called. |
134 | */ |
135 | SAL_DLLPUBLIC void SAL_CALL osl_terminateThread(oslThread Thread); |
136 | |
137 | /** Offers the rest of the threads time-slice to the OS. |
138 | scheduleThread() should be called in the working loop |
139 | of the thread, so any other thread could also get the |
140 | processor. Returns False if the thread should terminate, so |
141 | the thread could free any allocated resources. |
142 | */ |
143 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_scheduleThread(oslThread Thread); |
144 | |
145 | /** Offers the rest of the threads time-slice to the OS. |
146 | Under POSIX you _need_ to yield(), otherwise, since the |
147 | threads are not preempted during execution, NO other thread |
148 | (even with higher priority) gets the processor. Control is |
149 | only given to another thread if the current thread blocks |
150 | or uses yield(). |
151 | */ |
152 | SAL_DLLPUBLIC void SAL_CALL osl_yieldThread(void); |
153 | |
154 | /** Attempts to set the name of the current thread. |
155 | |
156 | The name of a thread is usually evaluated for debugging purposes. Not all |
157 | platforms support this. On Linux, a set thread name can be observed with |
158 | "ps -L". On Windows with the Microsoft compiler, a thread name set while a |
159 | debugger is attached can be observed within the debugger. |
160 | |
161 | @param name the name of the thread; must not be null; on Linux, only the |
162 | first 16 characters are used |
163 | */ |
164 | SAL_DLLPUBLIC void SAL_CALL osl_setThreadName(char const * name); |
165 | |
166 | /* Callback when data stored in a thread key is no longer needed */ |
167 | |
168 | typedef void (SAL_CALL *oslThreadKeyCallbackFunction)(void *); |
169 | |
170 | /** Create a key to an associated thread local storage pointer. */ |
171 | SAL_DLLPUBLIC oslThreadKey SAL_CALL osl_createThreadKey(oslThreadKeyCallbackFunction pCallback); |
172 | |
173 | /** Destroy a key to an associated thread local storage pointer. */ |
174 | SAL_DLLPUBLIC void SAL_CALL osl_destroyThreadKey(oslThreadKey Key); |
175 | |
176 | /** Get to key associated thread specific data. */ |
177 | SAL_DLLPUBLIC void* SAL_CALL osl_getThreadKeyData(oslThreadKey Key); |
178 | |
179 | /** Set to key associated thread specific data. */ |
180 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setThreadKeyData(oslThreadKey Key, void *pData); |
181 | |
182 | /** Get the current thread local text encoding. */ |
183 | SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL osl_getThreadTextEncoding(void); |
184 | |
185 | /** Set the thread local text encoding. |
186 | @return the old text encoding. |
187 | */ |
188 | SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL osl_setThreadTextEncoding(rtl_TextEncoding Encoding); |
189 | |
190 | #ifdef __cplusplus |
191 | } |
192 | #endif |
193 | |
194 | #endif // INCLUDED_OSL_THREAD_H |
195 | |
196 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
197 | |