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

Last change on this file since 576 was 573, checked in by alain, 6 years ago

Cosmetic.
File size: 17.2 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//////////////////////////////////////////////////////////////////////////////////////////////
28//             POSIX thread related functions
29//
30//  This include the thread creation/destruction, as well as the synchronisations:
31//  barriers, mutexes, and condition variables.
32//////////////////////////////////////////////////////////////////////////////////////////////
33
34#include <shared_pthread.h>
35
36/*********************************************************************************************
37 * This function creates a new user thread. The <user_attr> argument is a pointer
38 * on a structure containing the thread attributes, defined in thread.h file.
39 *********************************************************************************************
40 * @ trdid       : [out] buffer for created thread identifier in process.
41 * @ user_attr   : [in]  pointer on thread attributes structure.
42 * @ start_func  : [in]  pointer on start function.
43 * @ start_args  : [in]  pointer on start function arguments.
44 * @ return 0 if success / return -1 if failure.
45 ********************************************************************************************/
46int pthread_create( pthread_t            * trdid,
47                    const pthread_attr_t * attr,
48                    void                 * start_func,
49                    void                 * start_args );
50
51/*********************************************************************************************
52 * This blocking function causes the calling thread to wait for the termination of a target
53 * thread identified by the <trdid> argument. The <exit_value> defines the buffer to store
54 * the pointer returned by the terminating thread.
55 *********************************************************************************************
56 * @ trdid       : target thread identifier in process.
57 * @ start_args  : [in]  pointer on start function arguments.
58 * @ return 0 if success / return -1 if failure.
59 ********************************************************************************************/
60int pthread_join( pthread_t    trdid,
61                  void      ** exit_value );
62
63/*********************************************************************************************
64 * This function is used to indicate that storage for the target thread, identified by the
65 * <trdid> argument can be reclaimed when the thread terminates.
66 * If target thread has not terminated, pthread_detach() will not cause it to terminate.
67 *********************************************************************************************
68 * @ trdid       : target thread identifier in process.
69 * @ return 0 if success / return -1 if failure.
70 ********************************************************************************************/
71int pthread_detach( pthread_t   trdid );
72
73/*********************************************************************************************
74 * This function terminates the execution of the calling thread, and makes the exit_value
75 * pointer available to any successful pthread_join() with the terminating thread.
76 *********************************************************************************************
77 * @ exit_vallue  : [in] pointer to be returned to parent thread if thread is attached.
78 * @ return 0 if success / return -1 if failure.
79 ********************************************************************************************/
80int pthread_exit( void * exit_value );
81
82/*********************************************************************************************
83 * This function calls the scheduler for the core running the calling thread.
84 * WARNING: It is not defined by POSIX.
85 *********************************************************************************************
86 * @ return always 0.
87 ********************************************************************************************/
88int pthread_yield( void );
89
90
91//////////////////////////////////////////////////////////////////////////////////////////////
92//                 POSIX barrier related functions
93//
94// These functions are implemented in user space. Only the pthread_barrier_init() function
95// uses system calls to build the distributed quad-tree infrastructure.
96//////////////////////////////////////////////////////////////////////////////////////////////
97
98/*********************************************************************************************
99 * These structures defines a hierarchical, POSIX compliant, barrier.
100 * - If the barrier attribute in the pthread_barrier_init() is NULL, it is implemented
101 *   as a simple, sense reversing barrier, localised in the calling thread cluster.
102 * - If the barrier attribute is defined, it is implemented as a hierarchical, physically
103 *   distributed quad-tree, covering all clusters specified, with the following constraints:
104 *   . The involved clusters form a mesh [x_size * y_size]
105 *   . The lower left involved cluster is cluster(0,0) 
106 *   . The number of threads per cluster is the same in all clusters.
107 *
108 * Implementation note:
109 * - The quad three is implemented as a three dimensions array of node[x][y][l]
110 *   . [x][y] are the cluster coordinates / max values are (QDT_XMAX-1), (QDT_YMAX-1)
111 *   . [l] is the node level / 0 for terminal nodes / (QDT_LMAX-1) for the root node
112 ********************************************************************************************/
113
114#define  QDT_XMAX    16                /*! max number of clusters in a row                  */
115#define  QDT_YMAX    16                /*! max number of clusters in a column               */
116#define  QDT_LMAX    5                 /*! max depth of the quad tree                       */
117#define  QDT_YWIDTH  4                 /*! Y field in cxy, for cxy <=> (x,y) translation    */
118#define  QDT_YMASK   0xF               /*! Y field in cxy, for cxy <=> (x,y) translation    */
119
120typedef struct sqt_node_s
121{
122    volatile unsigned int sense;       /*! barrier state (toggle)                           */
123    volatile unsigned int count;       /*! number of not arrived tasks                      */
124    unsigned int          arity;       /*! number of locally expected tasks                 */
125    unsigned int          level;       /*! hierarchical level (0 is bottom)                 */
126    struct sqt_node_s   * parent;      /*! pointer on parent node (NULL for root)           */
127    struct sqt_node_s   * child[4];    /*! pointer on children node (NULL for bottom)       */
128}
129sqt_node_t;
130
131typedef struct pthread_barrier_s
132{
133    sqt_node_t          * node[QDT_XMAX][QDT_YMAX][QDT_LMAX];
134}
135pthread_barrier_t;
136
137typedef struct pthread_barrierattr_s
138{
139    unsigned int          x_size;      /*! number of clusters in a row (0 to x_size-1)      */
140    unsigned int          y_size;      /*! number of clusters in a column (0 to y_size-1)   */
141    unsigned int          nthreads;    /*! number of expected threads in a cluster          */
142}
143pthread_barrierattr_t;
144
145/*********************************************************************************************
146 * This function allocates resources required to use the barrier referenced by the <barrier>
147 * argument, and initializes the barrier from attributes referenced by the <attr> argument.
148 * If <attr> is NULL, the default barrier attributes shall be used.
149 * The results are undefined if pthread_barrier_init() is called when any thread is blocked
150 * on the barrier, or is used without first being initialized, or if pthread_barrier_init()
151 * is called specifying an already initialized barrier.
152 *********************************************************************************************
153 * @ barrier     : [in]  pointer on barrier in user space.
154 * @ attr        : [in]  pointer on attributes structure.
155 * @ count       : [in]  number of expected threads.
156 * @ return 0 if success / return EINVAL if illegal attributes.
157 ********************************************************************************************/
158int pthread_barrier_init( pthread_barrier_t           * barrier,
159                          const pthread_barrierattr_t * attr,
160                          unsigned int                  count ); 
161
162/*********************************************************************************************
163 * This function synchronizes participating threads at the barrier referenced by <barrier>.
164 * The calling is blocked until the required number of threads have called the function
165 * pthread_barrier_wait() specifying the barrier.
166 * When the required number of threads have called pthread_barrier_wait(), the constant
167 * PTHREAD_BARRIER_SERIAL_THREAD is returned to one unspecified thread and zero is returned
168 * to each of the remaining threads.
169 *********************************************************************************************
170 * @ barrier     : [in]  pointer on barrier in user space.
171 * @ return 0 if success / return EINVAL if the barrier was not properly initialized.
172 ********************************************************************************************/
173int pthread_barrier_wait( pthread_barrier_t * barrier );
174
175/*********************************************************************************************
176 * This function destroy the barrier referenced by <barrier> and release all resources used
177 * by the barrier. The effect of subsequent use of the barrier is undefined until the barrier
178 * is reinitialized by another call to pthread_barrier_init().
179 * An implementation may use this function to set barrier to an invalid value.
180 * The results are undefined if pthread_barrier_destroy() is called when a thread is blocked
181 * on the barrier, or if this function is called with an uninitialized barrier.
182 *********************************************************************************************
183 * @ barrier     : [in]  pointer on barrier in user space.
184 ********************************************************************************************/
185int pthread_barrier_destroy( pthread_barrier_t * barrier );
186   
187
188//////////////////////////////////////////////////////////////////////////////////////////////
189//                      POSIX mutex related functions
190//////////////////////////////////////////////////////////////////////////////////////////////
191
192/*********************************************************************************************
193 * This function initialise the mutex identified by the <mutex> argument.
194 * The <attr> argument is not supported yet, and must be NULL.
195 *********************************************************************************************
196 * @ mutex     : pointer on mutex in user space.
197 * @ attr      : pointer on attributes structure / must be NULL.
198 * @ return 0 if success / return -1 if failure.
199 ********************************************************************************************/
200int pthread_mutex_init( pthread_mutex_t           * mutex,
201                        const pthread_mutexattr_t * attr );
202
203/*********************************************************************************************
204 * This function destroy the mutex identified by the <mutex> argument.
205 *********************************************************************************************
206 * @ mutex     : pointer on mutex in user space.
207 * @ return 0 if success / return -1 if failure.
208 ********************************************************************************************/
209int pthread_mutex_destroy( pthread_mutex_t * mutex );
210
211/*********************************************************************************************
212 * This bloking function locks the mutex identified by the <mutex> argument,
213 * and blocks until it becomes available.
214 *********************************************************************************************
215 * @ mutex     : pointer on mutex in user space.
216 * @ return 0 if success / return -1 if failure.
217 ********************************************************************************************/
218int pthread_mutex_lock( pthread_mutex_t * mutex );
219
220/*********************************************************************************************
221 * This function unlocks the mutex identified by the <mutex> argument.
222 *********************************************************************************************
223 * @ mutex     : pointer on mutex in user space.
224 * @ return 0 if success / return -1 if failure.
225 ********************************************************************************************/
226int pthread_mutex_unlock( pthread_mutex_t * mutex );
227
228/*********************************************************************************************
229 * This function tries to lock the mutex identified by the <mutex> argument,
230 * but don't block if the mutex is locked by another thread, including the current thread.
231 *********************************************************************************************
232 * @ mutex     : pointer on mutex in user space.
233 * @ return 0 if success / return -1 if mutex already taken.
234 ********************************************************************************************/
235int pthread_mutex_trylock( pthread_mutex_t * mutex );
236
237
238//////////////////////////////////////////////////////////////////////////////////////////////
239//                      POSIX condvar related functions
240//////////////////////////////////////////////////////////////////////////////////////////////
241
242/*********************************************************************************************
243 * This function initializes a condition variable identified by the <cond> argument.
244 * WARNING: the <attr> argument is not supported and must be NULL.
245 *********************************************************************************************
246 * @ cond   : [in] pointer on condition in user space.
247 * @ attr   : [in] pointer on condition attribute (must be NULL).
248 * @ return 0 if success / return -1 if failure.
249 ********************************************************************************************/
250int pthread_cond_init( pthread_cond_t     * cond,
251                       pthread_condattr_t * attr );
252
253/*********************************************************************************************
254 * This function atomically unlocks the <mutex> and blocks the calling thread on the
255 * condition specified by the <cond> argument.  The thread unblocks only after another
256 * thread calls the pthread_cond_signal() or pthread_cond_broadcast() functions with the
257 * same condition variable.  The mutex must be locked before calling this function,
258 * otherwise the behavior is undefined. Before the pthread_cond_wait() function returns
259 * to the calling function, it re-acquires the <mutex>.
260 *********************************************************************************************
261 * @ cond      : pointer on condition in user space.
262 * @ mutex     : pointer on mutex in user space.
263 * @ return 0 if success / return -1 if failure.
264 ********************************************************************************************/
265int pthread_cond_wait( pthread_cond_t  * cond,
266                       pthread_mutex_t * mutex );
267
268/*********************************************************************************************
269 * This function unblocks one thread blocked on condition specified by the <cond> argument.
270 *********************************************************************************************
271 * @ cond      : pointer on condition in user space.
272 * @ return 0 if success / return -1 if failure.
273 ********************************************************************************************/
274int pthread_cond_signal( pthread_cond_t * cond );
275
276/*********************************************************************************************
277 * This function unblocks all threads blocked on condition specified by the <cond> argument.
278 *********************************************************************************************
279 * @ cond      : pointer on condition in user space.
280 * @ return 0 if success / return -1 if failure.
281 ********************************************************************************************/
282int pthread_cond_broadcast( pthread_cond_t * cond );
283
284/*********************************************************************************************
285 * This function delete the condition variable specified by the <cond> argument.
286 *********************************************************************************************
287 * @ cond      : pointer on condition in user space.
288 * @ return 0 if success / return -1 if failure.
289 ********************************************************************************************/
290int pthread_cond_destroy( pthread_cond_t * cond );
291
292
293
294#endif  // _PTHREAD_H_
Note: See TracBrowser for help on using the repository browser.