1 | /* |
---|
2 | * pthread.h - User level <pthread> library definition. |
---|
3 | * |
---|
4 | * Author Alain Greiner (2016,2017,2018,2019) |
---|
5 | * |
---|
6 | * Copyright (c) UPMC Sorbonne Universites |
---|
7 | * |
---|
8 | * This file is part of ALMOS-MKH. |
---|
9 | * |
---|
10 | * ALMOS-MKH is free software; you can redistribute it and/or modify it |
---|
11 | * under the terms of the GNU General Public License as published by |
---|
12 | * the Free Software Foundation; version 2.0 of the License. |
---|
13 | * |
---|
14 | * ALMOS-MKH is distributed in the hope that it will be useful, but |
---|
15 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
17 | * General Public License for more details. |
---|
18 | * |
---|
19 | * You should have received a copy of the GNU General Public License |
---|
20 | * along with ALMOS-MKH; if not, write to the Free Software Foundation, |
---|
21 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
---|
22 | */ |
---|
23 | |
---|
24 | #ifndef _PTHREAD_H_ |
---|
25 | #define _PTHREAD_H_ |
---|
26 | |
---|
27 | #include <shared_pthread.h> |
---|
28 | |
---|
29 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
30 | // POSIX thread related functions |
---|
31 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
32 | |
---|
33 | /********************************************************************************************* |
---|
34 | * This function creates a new user thread. The <user_attr> argument is a pointer |
---|
35 | * on a structure containing the thread attributes, defined in the shared_pthread.h file. |
---|
36 | ********************************************************************************************* |
---|
37 | * @ trdid : [out] buffer for created thread identifier in process. |
---|
38 | * @ attr : [in] pointer on user defined attributes structure. |
---|
39 | * @ start_func : [in] pointer on start function. |
---|
40 | * @ start_args : [in] pointer on start function arguments. |
---|
41 | * @ return 0 if success / return -1 if failure. |
---|
42 | ********************************************************************************************/ |
---|
43 | int pthread_create( pthread_t * trdid, |
---|
44 | const pthread_attr_t * attr, |
---|
45 | void * start_func, |
---|
46 | void * start_args ); |
---|
47 | |
---|
48 | /********************************************************************************************* |
---|
49 | * This blocking function causes the calling thread to wait for the termination of a target |
---|
50 | * thread identified by the <trdid> argument. The <exit_value> defines the buffer to store |
---|
51 | * the pointer returned by the terminating thread. |
---|
52 | ********************************************************************************************* |
---|
53 | * @ trdid : target thread identifier in process. |
---|
54 | * @ start_args : [in] pointer on start function arguments. |
---|
55 | * @ return 0 if success / return -1 if failure. |
---|
56 | ********************************************************************************************/ |
---|
57 | int pthread_join( pthread_t trdid, |
---|
58 | void ** exit_value ); |
---|
59 | |
---|
60 | /********************************************************************************************* |
---|
61 | * This function is used to indicate that storage for the target thread, identified by the |
---|
62 | * <trdid> argument can be reclaimed when the thread terminates. |
---|
63 | * If target thread has not terminated, pthread_detach() will not cause it to terminate. |
---|
64 | ********************************************************************************************* |
---|
65 | * @ trdid : target thread identifier in process. |
---|
66 | * @ return 0 if success / return -1 if failure. |
---|
67 | ********************************************************************************************/ |
---|
68 | int pthread_detach( pthread_t trdid ); |
---|
69 | |
---|
70 | /********************************************************************************************* |
---|
71 | * This function terminates the execution of the calling thread, and makes the exit_value |
---|
72 | * pointer available to any successful pthread_join() with the terminating thread. |
---|
73 | ********************************************************************************************* |
---|
74 | * @ exit_vallue : [in] pointer to be returned to parent thread if thread is attached. |
---|
75 | * @ return 0 if success / return -1 if failure. |
---|
76 | ********************************************************************************************/ |
---|
77 | int pthread_exit( void * exit_value ); |
---|
78 | |
---|
79 | /********************************************************************************************* |
---|
80 | * This function calls the scheduler for the core running the calling thread. |
---|
81 | * WARNING: It is not defined by POSIX. |
---|
82 | ********************************************************************************************* |
---|
83 | * @ return always 0. |
---|
84 | ********************************************************************************************/ |
---|
85 | int pthread_yield( void ); |
---|
86 | |
---|
87 | |
---|
88 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
89 | // POSIX mutex related functions |
---|
90 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
91 | |
---|
92 | /********************************************************************************************* |
---|
93 | * This function initialise the mutex identified by the <mutex> argument. |
---|
94 | * The <attr> argument is not supported yet, and must be NULL. |
---|
95 | ********************************************************************************************* |
---|
96 | * @ mutex : pointer on mutex in user space. |
---|
97 | * @ attr : pointer on attributes structure / must be NULL. |
---|
98 | * @ return 0 if success / return -1 if failure. |
---|
99 | ********************************************************************************************/ |
---|
100 | int pthread_mutex_init( pthread_mutex_t * mutex, |
---|
101 | const pthread_mutexattr_t * attr ); |
---|
102 | |
---|
103 | /********************************************************************************************* |
---|
104 | * This function destroy the mutex identified by the <mutex> argument. |
---|
105 | ********************************************************************************************* |
---|
106 | * @ mutex : pointer on mutex in user space. |
---|
107 | * @ return 0 if success / return -1 if failure. |
---|
108 | ********************************************************************************************/ |
---|
109 | int pthread_mutex_destroy( pthread_mutex_t * mutex ); |
---|
110 | |
---|
111 | /********************************************************************************************* |
---|
112 | * This bloking function locks the mutex identified by the <mutex> argument, |
---|
113 | * and blocks until it becomes available. |
---|
114 | ********************************************************************************************* |
---|
115 | * @ mutex : pointer on mutex in user space. |
---|
116 | * @ return 0 if success / return -1 if failure. |
---|
117 | ********************************************************************************************/ |
---|
118 | int pthread_mutex_lock( pthread_mutex_t * mutex ); |
---|
119 | |
---|
120 | /********************************************************************************************* |
---|
121 | * This function unlocks the mutex identified by the <mutex> argument. |
---|
122 | ********************************************************************************************* |
---|
123 | * @ mutex : pointer on mutex in user space. |
---|
124 | * @ return 0 if success / return -1 if failure. |
---|
125 | ********************************************************************************************/ |
---|
126 | int pthread_mutex_unlock( pthread_mutex_t * mutex ); |
---|
127 | |
---|
128 | /********************************************************************************************* |
---|
129 | * This function tries to lock the mutex identified by the <mutex> argument, |
---|
130 | * but don't block if the mutex is locked by another thread, including the current thread. |
---|
131 | ********************************************************************************************* |
---|
132 | * @ mutex : pointer on mutex in user space. |
---|
133 | * @ return 0 if success / return -1 if mutex already taken. |
---|
134 | ********************************************************************************************/ |
---|
135 | int pthread_mutex_trylock( pthread_mutex_t * mutex ); |
---|
136 | |
---|
137 | |
---|
138 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
139 | // POSIX condvar related functions |
---|
140 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
141 | |
---|
142 | /********************************************************************************************* |
---|
143 | * This function initializes a condition variable identified by the <cond> argument. |
---|
144 | * WARNING: the <attr> argument is not supported and must be NULL. |
---|
145 | ********************************************************************************************* |
---|
146 | * @ cond : [in] pointer on condition in user space. |
---|
147 | * @ attr : [in] pointer on condition attribute (must be NULL). |
---|
148 | * @ return 0 if success / return -1 if failure. |
---|
149 | ********************************************************************************************/ |
---|
150 | int pthread_cond_init( pthread_cond_t * cond, |
---|
151 | pthread_condattr_t * attr ); |
---|
152 | |
---|
153 | /********************************************************************************************* |
---|
154 | * This function atomically unlocks the <mutex> and blocks the calling thread on the |
---|
155 | * condition specified by the <cond> argument. The thread unblocks only after another |
---|
156 | * thread calls the pthread_cond_signal() or pthread_cond_broadcast() functions with the |
---|
157 | * same condition variable. The mutex must be locked before calling this function, |
---|
158 | * otherwise the behavior is undefined. Before the pthread_cond_wait() function returns |
---|
159 | * to the calling function, it re-acquires the <mutex>. |
---|
160 | ********************************************************************************************* |
---|
161 | * @ cond : pointer on condition in user space. |
---|
162 | * @ mutex : pointer on mutex in user space. |
---|
163 | * @ return 0 if success / return -1 if failure. |
---|
164 | ********************************************************************************************/ |
---|
165 | int pthread_cond_wait( pthread_cond_t * cond, |
---|
166 | pthread_mutex_t * mutex ); |
---|
167 | |
---|
168 | /********************************************************************************************* |
---|
169 | * This function unblocks one thread blocked on condition specified by the <cond> argument. |
---|
170 | ********************************************************************************************* |
---|
171 | * @ cond : pointer on condition in user space. |
---|
172 | * @ return 0 if success / return -1 if failure. |
---|
173 | ********************************************************************************************/ |
---|
174 | int pthread_cond_signal( pthread_cond_t * cond ); |
---|
175 | |
---|
176 | /********************************************************************************************* |
---|
177 | * This function unblocks all threads blocked on condition specified by the <cond> argument. |
---|
178 | ********************************************************************************************* |
---|
179 | * @ cond : pointer on condition in user space. |
---|
180 | * @ return 0 if success / return -1 if failure. |
---|
181 | ********************************************************************************************/ |
---|
182 | int pthread_cond_broadcast( pthread_cond_t * cond ); |
---|
183 | |
---|
184 | /********************************************************************************************* |
---|
185 | * This function delete the condition variable specified by the <cond> argument. |
---|
186 | ********************************************************************************************* |
---|
187 | * @ cond : pointer on condition in user space. |
---|
188 | * @ return 0 if success / return -1 if failure. |
---|
189 | ********************************************************************************************/ |
---|
190 | int pthread_cond_destroy( pthread_cond_t * cond ); |
---|
191 | |
---|
192 | |
---|
193 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
194 | // POSIX barrier related functions |
---|
195 | ////////////////////////////////////////////////////////////////////////////////////////////// |
---|
196 | |
---|
197 | /********************************************************************************************* |
---|
198 | * This function allocates resources required to use the barrier referenced by the <barrier> |
---|
199 | * argument, and initializes the barrier from attributes referenced by the <attr> argument. |
---|
200 | * If <attr> is NULL, the default barrier attributes shall be used. |
---|
201 | * The results are undefined if pthread_barrier_init() is called when any thread is blocked |
---|
202 | * on the barrier, or is used without first being initialized, or if pthread_barrier_init() |
---|
203 | * is called specifying an already initialized barrier. |
---|
204 | ********************************************************************************************* |
---|
205 | * @ barrier : [in] pointer on barrier in user space. |
---|
206 | * @ attr : [in] pointer on attributes structure. |
---|
207 | * @ count : [in] number of expected threads. |
---|
208 | * @ return 0 if success / return EINVAL if illegal attributes. |
---|
209 | ********************************************************************************************/ |
---|
210 | int pthread_barrier_init( pthread_barrier_t * barrier, |
---|
211 | const pthread_barrierattr_t * attr, |
---|
212 | unsigned int count ); |
---|
213 | |
---|
214 | /********************************************************************************************* |
---|
215 | * This function synchronizes participating threads at the barrier referenced by <barrier>. |
---|
216 | * The calling is blocked until the required number of threads have called the function |
---|
217 | * pthread_barrier_wait() specifying the barrier. |
---|
218 | * When the required number of threads have called pthread_barrier_wait(), the constant |
---|
219 | * PTHREAD_BARRIER_SERIAL_THREAD is returned to one unspecified thread and zero is returned |
---|
220 | * to each of the remaining threads. |
---|
221 | ********************************************************************************************* |
---|
222 | * @ barrier : [in] pointer on barrier in user space. |
---|
223 | * @ return 0 if success / return EINVAL if the barrier was not properly initialized. |
---|
224 | ********************************************************************************************/ |
---|
225 | int pthread_barrier_wait( pthread_barrier_t * barrier ); |
---|
226 | |
---|
227 | /********************************************************************************************* |
---|
228 | * This function destroy the barrier referenced by <barrier> and release all resources used |
---|
229 | * by the barrier. The effect of subsequent use of the barrier is undefined until the barrier |
---|
230 | * is reinitialized by another call to pthread_barrier_init(). |
---|
231 | * An implementation may use this function to set barrier to an invalid value. |
---|
232 | * The results are undefined if pthread_barrier_destroy() is called when a thread is blocked |
---|
233 | * on the barrier, or if this function is called with an uninitialized barrier. |
---|
234 | ********************************************************************************************* |
---|
235 | * @ barrier : [in] pointer on barrier in user space. |
---|
236 | ********************************************************************************************/ |
---|
237 | int pthread_barrier_destroy( pthread_barrier_t * barrier ); |
---|
238 | |
---|
239 | |
---|
240 | |
---|
241 | #endif // _PTHREAD_H_ |
---|