Changeset 573 for trunk/libs/libpthread/pthread.h

Timestamp:

Oct 5, 2018, 12:21:52 AM (6 years ago)

Author:

alain

Message:

Cosmetic.

File:

• trunk/libs/libpthread/pthread.h (modified) (8 diffs)

trunk/libs/libpthread/pthread.h

@@ -2 +2 @@
  * pthread.h - User level <pthread> library definition.
  * 
- * Author     Alain Greiner (2016,2017)
+ * Author     Alain Greiner (2016,2017,2018)
  *
  * Copyright (c) UPMC Sorbonne Universites
@@ -26 +26 @@
 
 //////////////////////////////////////////////////////////////////////////////////////////////
-//             POSIX Threads related functions (including barriers and mutexes)
+//             POSIX thread related functions
+// 
+//  This include the thread creation/destruction, as well as the synchronisations:
+//  barriers, mutexes, and condition variables.
 //////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -72 +75 @@
  * pointer available to any successful pthread_join() with the terminating thread.
  *********************************************************************************************
- * @ exit_vallue  : [in] pointer to be returned to parent thread if thead is attached.
+ * @ exit_vallue  : [in] pointer to be returned to parent thread if thread is attached.
  * @ return 0 if success / return -1 if failure.
  ********************************************************************************************/
@@ -85 +88 @@
 int pthread_yield( void );
 
-//////////////////////////////////////////////////////////////////////////////////////////////
-//                 POSIX Barriers related functions
+
+//////////////////////////////////////////////////////////////////////////////////////////////
+//                 POSIX barrier related functions
 //
 // These functions are implemented in user space. Only the pthread_barrier_init() function
-// uses syscalls to build the distributed quad-tree infrastructure.
+// uses system calls to build the distributed quad-tree infrastructure.
 //////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -100 +104 @@
  *   . The involved clusters form a mesh [x_size * y_size]
  *   . The lower left involved cluster is cluster(0,0)  
- *   . The number of threads in a cluster is the same in all clusters.
+ *   . The number of threads per cluster is the same in all clusters.
  *
  * Implementation note:
@@ -183 +187 @@
 
 //////////////////////////////////////////////////////////////////////////////////////////////
-//                      POSIX Mutexes
-//
-// These functions are implemented in user space, and do not use syscalls.
-// This implementation uses a ticket based policy to enforce fairness.
-//////////////////////////////////////////////////////////////////////////////////////////////
-
-typedef struct pthread_mutex_s
-{
-    volatile unsigned int current;   /*! current index                                      */
-    volatile unsigned int free;      /*! next free ticket index                             */
-}
-pthread_mutex_t;
-
-typedef struct pthread_mutexattr_s
-{
-    int          bloup;              /*! unused                                             */
-}
-pthread_mutexattr_t;
+//                      POSIX mutex related functions
+//////////////////////////////////////////////////////////////////////////////////////////////
 
 /********************************************************************************************* 
@@ -231 +219 @@
 
 /********************************************************************************************* 
+ * This function unlocks the mutex identified by the <mutex> argument.
+ *********************************************************************************************
+ * @ mutex     : pointer on mutex in user space.
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_mutex_unlock( pthread_mutex_t * mutex );
+
+/********************************************************************************************* 
  * This function tries to lock the mutex identified by the <mutex> argument,
  * but don't block if the mutex is locked by another thread, including the current thread.
@@ -239 +235 @@
 int pthread_mutex_trylock( pthread_mutex_t * mutex );
 
-/********************************************************************************************* 
- * This function unlocks the mutex identified by the <mutex> argument.
- *********************************************************************************************
- * @ mutex     : pointer on mutex in user space.
- * @ return 0 if success / return -1 if failure.
- ********************************************************************************************/
-int pthread_mutex_unlock( pthread_mutex_t * mutex );
+
+//////////////////////////////////////////////////////////////////////////////////////////////
+//                      POSIX condvar related functions
+//////////////////////////////////////////////////////////////////////////////////////////////
+
+/********************************************************************************************* 
+ * This function initializes a condition variable identified by the <cond> argument.
+ * WARNING: the <attr> argument is not supported and must be NULL.
+ *********************************************************************************************
+ * @ cond   : [in] pointer on condition in user space.
+ * @ attr   : [in] pointer on condition attribute (must be NULL).
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_cond_init( pthread_cond_t     * cond,
+                       pthread_condattr_t * attr );
+
+/********************************************************************************************* 
+ * This function atomically unlocks the <mutex> and blocks the calling thread on the 
+ * condition specified by the <cond> argument.  The thread unblocks only after another
+ * thread calls the pthread_cond_signal() or pthread_cond_broadcast() functions with the
+ * same condition variable.  The mutex must be locked before calling this function,
+ * otherwise the behavior is undefined. Before the pthread_cond_wait() function returns
+ * to the calling function, it re-acquires the <mutex>.
+ *********************************************************************************************
+ * @ cond      : pointer on condition in user space.
+ * @ mutex     : pointer on mutex in user space.
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_cond_wait( pthread_cond_t  * cond,
+                       pthread_mutex_t * mutex );
+
+/********************************************************************************************* 
+ * This function unblocks one thread blocked on condition specified by the <cond> argument. 
+ *********************************************************************************************
+ * @ cond      : pointer on condition in user space.
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_cond_signal( pthread_cond_t * cond );
+
+/********************************************************************************************* 
+ * This function unblocks all threads blocked on condition specified by the <cond> argument. 
+ *********************************************************************************************
+ * @ cond      : pointer on condition in user space.
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_cond_broadcast( pthread_cond_t * cond );
+
+/********************************************************************************************* 
+ * This function delete the condition variable specified by the <cond> argument. 
+ *********************************************************************************************
+ * @ cond      : pointer on condition in user space.
+ * @ return 0 if success / return -1 if failure.
+ ********************************************************************************************/
+int pthread_cond_destroy( pthread_cond_t * cond );
+