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

Last change on this file since 647 was 647, checked in by alain, 4 years ago

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