From 0d460b28c769fd2a1d2efb85f11edd4189fb5713 Mon Sep 17 00:00:00 2001
From: zilio nicolas <nicolas.zilio@kit.edu>
Date: Fri, 11 Sep 2015 15:36:17 +0200
Subject: reviewd old tasks comments for doxygen and update

---
 pcilib/lock.c | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

(limited to 'pcilib/lock.c')

diff --git a/pcilib/lock.c b/pcilib/lock.c
index 03a2377..25e12a5 100644
--- a/pcilib/lock.c
+++ b/pcilib/lock.c
@@ -18,22 +18,21 @@
 #include "lock.h"
 #include "pci.h"
 
-
+/**
+ * structure to define a lock
+ */
 struct pcilib_lock_s {
-    pthread_mutex_t mutex;
-    pcilib_lock_flags_t flags;
+  pthread_mutex_t mutex; /**< the pthread robust mutex itself*/
+  pcilib_lock_flags_t flags; /**<flag to define the property of the mutex*/
 #ifdef HAVE_STDATOMIC_H
-    volatile atomic_uint refs;
+  volatile atomic_uint refs; /**< approximate number of processes that may require access to this lock*/ 
 #else /* HAVE_STDATOMIC_H */
-    volatile uint32_t refs;
+    volatile uint32_t refs;/**< approximate number of processes that may require access to this lock*/
 #endif /* HAVE_STDATOMIC_H */
-    char name[];
+  char name[]; /**< identifier name to search for a lock*/
 };
 
 
-/**
- * this function initialize a new semaphore in the kernel if it's not already initialized given the key that permits to differentiate semaphores, and then return the integer that points to the semaphore that have been initialized or to a previously already initialized semaphore
- */
 int pcilib_init_lock(pcilib_lock_t *lock, pcilib_lock_flags_t flags, const char *lock_id) {
     int err;
     pthread_mutexattr_t attr;
@@ -53,11 +52,13 @@ int pcilib_init_lock(pcilib_lock_t *lock, pcilib_lock_flags_t flags, const char
 	return PCILIB_ERROR_FAILED;
     }
 
+	/* we declare the mutex as possibly shared amongst different processes*/
     if ((err = pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED))!=0) {
 	pcilib_error("Can't configure a shared mutex attribute, errno %i", errno);
 	return PCILIB_ERROR_FAILED;
     }
 
+	/* we set the mutex as robust, so it would be automatically unlocked if the application crash*/
     if ((flags&PCILIB_LOCK_FLAG_PERSISTENT)==0) {
 	if ((err = pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST))!=0) {
 	    pcilib_error("Can't configure a robust mutex attribute, errno: %i", errno);
@@ -78,9 +79,6 @@ int pcilib_init_lock(pcilib_lock_t *lock, pcilib_lock_flags_t flags, const char
 }
 
 
-/*
- * we uninitialize a mutex and set its name to 0 pointed by lock_ctx with this function. setting name to is the real destroying operation, but we need to unitialize the lock to initialize it again after
- */
 void pcilib_free_lock(pcilib_lock_t *lock) {
     int err;
 
@@ -134,9 +132,6 @@ const char *pcilib_lock_get_name(pcilib_lock_t *lock) {
     return NULL;
 }
 
-/*
- * this function will take the lock for the semaphore pointed by semId
- */
 int pcilib_lock_custom(pcilib_lock_t *lock, pcilib_lock_flags_t flags, pcilib_timeout_t timeout) {
     int err;
 
@@ -149,12 +144,15 @@ int pcilib_lock_custom(pcilib_lock_t *lock, pcilib_lock_flags_t flags, pcilib_ti
 
     switch (timeout) {
      case PCILIB_TIMEOUT_INFINITE:
+	/* the process will be hold till it can gain acquire the lock*/
         err = pthread_mutex_lock(&lock->mutex);
 	break;
      case PCILIB_TIMEOUT_IMMEDIATE:
+	/* the function returns immediatly if it can't acquire the lock*/
         err = pthread_mutex_trylock(&lock->mutex);
 	break;
      default:
+	/* the process will be hold till it can acquire the lock and timeout is not reached*/
         clock_gettime(CLOCK_REALTIME, &tm);
         tm.tv_nsec += 1000 * (timeout%1000000);
         if (tm.tv_nsec < 1000000000)
@@ -171,6 +169,7 @@ int pcilib_lock_custom(pcilib_lock_t *lock, pcilib_lock_flags_t flags, pcilib_ti
 
     switch (err) {
      case EOWNERDEAD:
+	/*in the case an application with a lock acquired crashes, this lock becomes inconsistent. we have so to make it consistent again to use it again.*/
         err = pthread_mutex_consistent(&lock->mutex);
         if (err) {
 	    pcilib_error("Failed to mark mutex as consistent, errno %i", err);
@@ -195,9 +194,6 @@ int pcilib_try_lock(pcilib_lock_t* lock) {
     return pcilib_lock_custom(lock, PCILIB_LOCK_FLAGS_DEFAULT, PCILIB_TIMEOUT_IMMEDIATE);
 }
 
-/**
- * this function will unlock the semaphore pointed by lock_ctx.
- */
 void pcilib_unlock(pcilib_lock_t *lock) {
     int err;
 
-- 
cgit v1.2.3