diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html index 554915b7722..c424662d0df 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: