From 62d058a834efef73adb0483716f3efee11db996c Mon Sep 17 00:00:00 2001 From: patacongo Date: Sat, 31 May 2008 18:02:49 +0000 Subject: [PATCH] Comment updates git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@754 42af7a65-404d-4744-a932-0658087f49c3 --- Documentation/NuttxUserGuide.html | 80 +++++++++++++++++++++++++++---- sched/pthread_initialize.c | 52 ++++++++++---------- sched/pthread_mutexlock.c | 32 +++++++++++-- sched/pthread_mutextrylock.c | 14 ++++-- sched/pthread_mutexunlock.c | 4 ++ 5 files changed, 142 insertions(+), 40 deletions(-) diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html index 554915b772..c424662d0d 100644 --- a/Documentation/NuttxUserGuide.html +++ b/Documentation/NuttxUserGuide.html @@ -4697,7 +4697,10 @@ returned to indicate the error: A thread attempting to unlock an unlocked mutex will return with an error.
  • PTHREAD_MUTEX_DEFAULT. The default mutex type (PTHREAD_MUTEX_NORMAL).
    • - In NuttX, PTHREAD_MUTEX_NORMAL is not implemented. PTHREAD_MUTEX_ERRORCHECK is the normal behavior. +

    + In NuttX, PTHREAD_MUTEX_NORMAL is not implemented. Rather, the behavior described + for PTHREAD_MUTEX_ERRORCHECK is the normal behavior. +

    Returned Values: @@ -4786,22 +4789,57 @@ interface of the same name.

    Description: + The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). + If the mutex is already locked, the calling thread blocks until the mutex + becomes available. This operation returns with the mutex object referenced + by mutex in the locked state with the calling thread as its owner. +

    +

    + If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. + Attempting to relock the mutex causes deadlock. If a thread attempts to unlock + a mutex that it has not locked or a mutex which is unlocked, undefined behavior + results. +

    +

    + In NuttX, PTHREAD_MUTEX_NORMAL is not implemented. Rather, the behavior described + for PTHREAD_MUTEX_ERRORCHECK is the normal behavior. +

    +

    + If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. + If a thread attempts to relock a mutex that it has already locked, an error + will be returned. If a thread attempts to unlock a mutex that it has not + locked or a mutex which is unlocked, an error will be returned. +

    +

    + If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept + of a lock count. When a thread successfully acquires a mutex for the first time, + the lock count is set to one. Every time a thread relocks this mutex, the lock count + is incremented by one. Each time the thread unlocks the mutex, the lock count is + decremented by one. When the lock count reaches zero, the mutex becomes available + for other threads to acquire. If a thread attempts to unlock a mutex that it has + not locked or a mutex which is unlocked, an error will be returned. +

    +

    + If a signal is delivered to a thread waiting for a mutex, upon return from + the signal handler the thread resumes waiting for the mutex as if it was + not interrupted. +

    Input Parameters:

    Returned Values:

    -If successful, the pthread_mutex_lock() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: +If successful, the pthread_mutex_lock() function will return zero (OK). +Otherwise, an error number will be returned to indicate the error:

    +

    Note that this function will never return the error EINTR.

    Assumptions/Limitations:

    POSIX Compatibility: Comparable to the POSIX @@ -4817,22 +4855,31 @@ interface of the same name.

    Description: + The function pthread_mutex_trylock() is identical to pthread_mutex_lock() + except that if the mutex object referenced by mutex is currently locked + (by any thread, including the current thread), the call returns immediately + with the errno EBUSY. +

    + If a signal is delivered to a thread waiting for a mutex, upon return from + the signal handler the thread resumes waiting for the mutex as if it was + not interrupted. +

    Input Parameters:

    Returned Values:

    -If successful, the pthread_mutex_trylock() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: +If successful, the pthread_mutex_trylock() function will return zero (OK). +Otherwise, an error number will be returned to indicate the error:

    +

    Note that this function will never return the error EINTR.

    Assumptions/Limitations:

    POSIX Compatibility: Comparable to the POSIX @@ -4849,6 +4896,20 @@ interface of the same name.

    Description:

    + The pthread_mutex_unlock() function releases the mutex object referenced + by mutex. The manner in which a mutex is released is dependent upon the + mutex's type attribute. If there are threads blocked on the mutex object + referenced by mutex when pthread_mutex_unlock() is called, resulting in + the mutex becoming available, the scheduling policy is used to determine + which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE + mutexes, the mutex becomes available when the count reaches zero and the + calling thread no longer has any locks on this mutex). +

    +

    + If a signal is delivered to a thread waiting for a mutex, upon return from + the signal handler the thread resumes waiting for the mutex as if it was + not interrupted. +

    Input Parameters: