source: trunk/libs/libpthread/pthread.h @ 615

Last change on this file since 615 was 581, checked in by alain, 6 years ago

1) Improve the busylock debug infrastructure.
2) introduce a non-distributed, but portable implementation for the pthread_barrier.
File size: 14.4 KB
Line 
1/*
2 * pthread.h - User level <pthread> library definition.
3 *
4 * Author     Alain Greiner (2016,2017,2018)
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 thread.h file.
36 *********************************************************************************************
37 * @ trdid       : [out] buffer for created thread identifier in process.
38 * @ user_attr   : [in]  pointer on thread 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 ********************************************************************************************/
43int 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 ********************************************************************************************/
57int 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 ********************************************************************************************/
68int 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 ********************************************************************************************/
77int 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 ********************************************************************************************/
85int 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 ********************************************************************************************/
100int 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 ********************************************************************************************/
109int 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 ********************************************************************************************/
118int 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 ********************************************************************************************/
126int 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 ********************************************************************************************/
135int 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 ********************************************************************************************/
150int 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 ********************************************************************************************/
165int 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 ********************************************************************************************/
174int 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 ********************************************************************************************/
182int 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 ********************************************************************************************/
190int 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 ********************************************************************************************/
210int 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 ********************************************************************************************/
225int 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 ********************************************************************************************/
237int pthread_barrier_destroy( pthread_barrier_t * barrier );
238   
239
240
241#endif  // _PTHREAD_H_
Note: See TracBrowser for help on using the repository browser.