Index: trunk/kernel/libk/remote_mutex.h
===================================================================
--- trunk/kernel/libk/remote_mutex.h	(revision 457)
+++ trunk/kernel/libk/remote_mutex.h	(revision 563)
@@ -1,6 +1,6 @@
 /*
- * remote_mutex.h -  remote_mutex operations definition.
+ * remote_mutex.h -  POSIX mutex definition.
  *
- * Authors   Alain Greiner   (2016)
+ * Authors   Alain Greiner   (2016,2017,2018)
  * 
  * Copyright (c) UPMC Sorbonne Universites
@@ -30,9 +30,8 @@
 
 /***************************************************************************************
- *    This file defines a POSIX compliant mutex.
+ *    This file defines an user level POSIX compliant mutex.
  *
- * It is used by muti-threaded applications to synchronise threads running in
- * different clusters, as all access functions uses hal_remote_lw() / hal_remote_sw() 
- * portable remote access primitives.
+ * It can be used by muti-threaded user applications to synchronise user threads
+ * running in different clusters.
  *
  * A mutex is declared by a given user process as a "pthread_mutex_t" global variable.
@@ -41,5 +40,5 @@
  * For each user mutex, ALMOS-MKH creates a kernel "remote_mutex_t" structure,
  * dynamically allocated in the reference cluster by the remote_mutex_create() function, 
- * and destroyed by the remote_barrier_destroy() function, using RPC if the calling thread
+ * and destroyed by the remote_mutex_destroy() function, using RPC if the calling thread
  * is not running in the reference cluster. 
  *
@@ -53,18 +52,15 @@
 
 /*****************************************************************************************
- * This structure defines the mutex descriptor.
- * - It contains an xlist of all mutex dynamically created by a given process,
- *   rooted in the reference process descriptor.
- * - It contains the root of another xlist to register all waiting threads.
+ * This structure defines the kernel implementation of an user level mutex.
  ****************************************************************************************/
 
 typedef struct remote_mutex_s
 {
-    remote_spinlock_t  lock;            /*! lock protecting list of waiting threads   */
+    remote_busylock_t  lock;            /*! lock protecting the mutex state           */
     intptr_t           ident;           /*! mutex identifier (vaddr in user space)    */ 
-    uint32_t           value;           /*! mutex non allocated if 0                  */
-    xptr_t             owner;           /*! extended pointer on owner thread          */
+    uint32_t           taken;           /*! mutex non allocated if 0                  */
     xlist_entry_t      list;            /*! member of list of mutex in same process   */
     xlist_entry_t      root;            /*! root of list of waiting threads           */
+    xptr_t             owner;           /*! extended pointer on owner thread          */
 }
 remote_mutex_t;
@@ -81,5 +77,5 @@
 
 /***************************************************************************************
- * This function implement the pthread_mutex_init() syscall.
+ * This function implements the pthread_mutex_init() syscall.
  * It allocates memory for the mutex descriptor in the reference cluster for
  * the calling process, it initializes the mutex state, and register it in the 
@@ -87,10 +83,10 @@
  ***************************************************************************************
  * @ ident       : mutex identifier (virtual address in user space).
- * @ return 0 if success / return ENOMEM if failure.
+ * @ return 0 if success / ENOMEM if no memory / EINVAL if invalid argument.
  **************************************************************************************/
 error_t remote_mutex_create( intptr_t ident );
 
 /***************************************************************************************
- * This function implement the pthread_mutex_destroy() syscall.
+ * This function implements the pthread_mutex_destroy() syscall.
  * It releases thr memory allocated for the mutex descriptor, and remove the mutex 
  * from the list of mutex owned by the reference process.
@@ -101,5 +97,8 @@
 
 /***************************************************************************************
- * This blocking function get ownership of a remote mutex.
+ * This blocking function implements the pthread_mutex_lock() syscall.
+ * It returns only when the ownership of the mutex identified by the <mutex_xp>
+ * argument has been obtained by the calling thread. It register in the mutex waiting 
+ * queue when the mutex is already taken by another thread.
  ***************************************************************************************
  * @ mutex_xp  : extended pointer on mutex descriptor.
@@ -108,9 +107,22 @@
 
 /***************************************************************************************
- * This function releases a remote mutex.
+ * This function implements the pthread_mutex_unlock() syscall.
+ * It cheks that the calling thread is actually the mutex owner.
+ * It reset the "taken" & "owner" fields for the mutex identified by <mutex_xp>.
+ * It unblocks the first thread registered in the mutex waiting queue, when the 
+ * queue is not empty.
  ***************************************************************************************
  * @ mutex_xp  : extended pointer on mutex descriptor.
+ * @ return 0 if success / return non zero if calling thread is not mutex owner. 
  **************************************************************************************/
-void remote_mutex_unlock( xptr_t  mutex_xp );
+error_t remote_mutex_unlock( xptr_t  mutex_xp );
+
+/***************************************************************************************
+ * This non blocking function function attempts to lock a mutex without blocking.
+ ***************************************************************************************
+ * @ mutex_xp  : extended pointer on mutex descriptor.
+ * @ return 0 if success / return non zero if already taken.
+ **************************************************************************************/
+error_t remote_mutex_trylock( xptr_t  mutex_xp );
 
 
