Re: [PATCTH 0/2] pthread_mutexattr_setrobust() and pthread_mutex_consistent()

[Yubin Ruan <ablacktshirt at gmail dot com>]

Here are the man page in plain text, in case you want to read it
directly in the email.

FYI, I obtain information about these API mainly from reading the
source and testing. If you find anything wrong, please kindly reply
and point it out.

Many thanks!
Yubin

--- pthread_mutexattr_setrobust() and pthread_mutexattr_getrobust() ---

Name
  pthread_mutexattr_getrobust, pthread_mutexattr_setrobust,
  pthread_mutexattr_getrobust_np, pthread_mutexattr_setrobust_np

  -- get and set the robustness attribute of a mutex attribute object

SYNOPSIS
  #include <pthread.h>

 int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr, int
*robustness);
 int pthread_mutexattr_setrobust(const pthread_mutexattr_t *attr, int
*robustness);
 int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr,
int *robustness);
 int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr,
int *robustness);

  Compile and link with -pthread.

DESCRIPTION
  The pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() functions
  get and set the robustness attribute of a initialized mutex attribute object,
  respectively. The robustness attribute specify the behavior of the mutex when
  its owner dies without unlocking it. These two functions are
specified in POSIX.
  Glibc's NPTL has pthread_mutexattr_getrobust_np() and
pthread_mutexattr_setrobust_np()
  respectively but they are just aliases, with the "np" standing for
"Native Posix".
  See NPTL(7).

  Currently there are only two possible values for the robustness attribute:

  PTHREAD_MUTEX_STALLED is the default value for a mutex attribute object. If a
  mutex is initialized with a PTHREAD_MUTEX_STALLED attribute object and its
  owner dies without unlocking it, it is kept locked afterwards and any future
  attempts to call pthread_mutex_lock() on this mutex will block indefinitely.

  PTHREAD_MUTEX_ROBUST can be set on a mutex attribute object so that when the
  owner of the mutex dies or when the process containing such a locked mutex
  performs execve(2), any future attempts to call pthread_mutex_lock() on this
  mutex will suceed and return EOWNERDEAD to indicate that the original owner no
  longer exists and the mutex is left in an inconsisten state. After EOWNERDEAD
  is returned, the next owner should call pthread_mutex_consistent(3) on the
  acquired mutex to make it consistent again before using it any further. If the
  next owner calls pthread_mutex_unlock(3) before making it consistent, the
  mutex will be unusable permanently and any subsequent attempts to
lock it using
  pthread_mutex_lock(3) will return ENORECOVERABLE. If the next owner terminates
  before calling pthread_mutex_consistent(3), furture pthread_mutex_lock(3) on
  this mutex will still return EOWNERDEAD.

  Glibc defined PTHREAD_MUTEX_STALLED_NP and PTHREAD_MUTEX_ROBUST_NP as aliases
  of PTHREAD_MUTEX_STALLED and PTHREAD_MUTEX_ROBUST respectively.

  Note that the *attr* argument of pthread_mutexattr_getrobust() and
  pthread_mutexattr_setrobust() should refer to a mutex attribute object that
  was initialized by pthread_mutexattr_init(3), otherwise the behavior is
  undefined.

RETURN VALUE
  On success, zero is returned by pthread_mutexattr_getrobust() and the value
  pointed to by the *robustness* parameter is set to the robustness attribute
  of *attr*. Otherwise, an error number shall be returned. On success
  pthread_mutexattr_setrobust() set the robustness attribute into the mutex
  attribute object *attr* and return zero, otherwise a error number is returned
  to indicate the error.

  [Glibc-specificed features]
  In glibc's implementation, pthread_mutexattr_getrobust() always return zero.

ERRORS

  EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST is
  passed into pthread_mutexattr_setrobust().

EXAMPLES

    #include <stdio.h>
    #include <unistd.h>
    #include <pthread.h>
    #include <errno.h>

    pthread_mutex_t lock;

    void *original_owner_thread(void *ptr)
    {
        printf("[original owner] Setting lock...\n");
        pthread_mutex_lock(&lock);
        printf("[original owner] Locked. Now exiting without unlocking.\n");
        pthread_exit(NULL);
    }

    int main(int argc, char *argv[])
    {
        pthread_t lock_getter;
        pthread_mutexattr_t attr;
        pthread_mutexattr_init(&attr);   /* initialize the attribute object */
        pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); /*
set robustness */

        pthread_mutex_init(&lock, &attr);   /* initialize the lock */

        pthread_create(&lock_getter, NULL, original_owner_thread, NULL);
        sleep(2);   /* original_owner_thread should have exited now */

        printf("Attempting to acquire unlock robust mutex.\n");
        int ret_code = pthread_mutex_lock(&lock);
        if(EOWNERDEAD == ret_code) {
            printf("EOWNERDEAD returned. Make the mutex consistent now\n");
            pthread_mutex_consistent(&lock);
        }

        pthread_mutex_unlock(&lock);

        return 0;
    }


SEE ALSO
    pthread_mutexattr_init(3), pthread_mutex_consistent(3),
    pthread_mutex_lock(3)

--- END ---

--- pthread_mutex_consistent() ---

NAME
    pthread_mutex_consistent - make the robust mutex consistent

SYNOPSIS
    #include <pthread.h>
    int pthread_mutex_consistent(pthread_mutex_t *mutex)

    Compile and link with -pthread.

DESCRIPTION
    This function make a robust mutex consistent if it is in a inconsistent
    state. A mutex can be left in a inconsistent state if its owner terminate
    while holding the mutex, in which situation the next owner who acquire the
    mutex will succeed and be notified by the return value of EOWNERDEAD.

RETURN VALUE
    On success, pthread_mutex_consistent() return 0. Otherwise an error value
    is returned to indicate the error.

ERRORS
    EINVAL The mutex is either not robust or is not in a inconsistent state.

SEE ALSO
    pthread_mutex_lock(3), pthread_mutexattr_init(3),
    pthread_mutexattr_setrobust(3), pthread_mutexattr_getrobust(3)


---- END ---

/*
 * This program is used to verify that when the owner of a non-robust lock exit
 * prematurely without unlocking the mutex, the next owner will be block
 * indefintely.
 *
 * Compile and link with -pthread
 */

#include <stdio.h>
#include <unistd.h>
#include <pthread.h>
#include <errno.h>

pthread_mutex_t lock;

void *original_owner_thread(void *ptr)
{
    printf("[original owner] Setting lock...\n");
    pthread_mutex_lock(&lock);
    printf("[original owner] Locked. Now exiting without unlocking.\n");
    pthread_exit(NULL);
}

int main(int argc, char *argv[]) 
{
    pthread_t lock_getter;
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);   /* initialize the attribute object */
    pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);

    pthread_mutex_init(&lock, &attr);   /* initialize the lock */

    pthread_create(&lock_getter, NULL, original_owner_thread, NULL);
    sleep(2);   /* original_owner_thread should have exited now */

    printf("Attempting to acquire unlock robust mutex.\n");
    int ret_code = pthread_mutex_lock(&lock);
    if(EOWNERDEAD == ret_code) {
        printf("EOWNERDEAD returned. Make the mutex consistent now\n");
        pthread_mutex_consistent(&lock);
    }

    pthread_mutex_unlock(&lock);

    return 0;
}

/*
 * This program is used to verify that when the owner of a non-robust lock exit
 * prematurely without unlocking the mutex, the next owner will be block
 * indefintely.
 */

#include <stdio.h>
#include <unistd.h>
#include <pthread.h>
#include <errno.h>

pthread_mutex_t lock;

void *original_owner_thread(void *ptr)
{
    printf("[original owner] Setting lock...\n");
    pthread_mutex_lock(&lock);
    printf("[original owner] Locked. Now exiting without unlocking.\n");
    pthread_exit(NULL);
}

int main(int argc, char *argv[]) 
{
    pthread_t lock_getter;
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);   /* initialize the attribute object */
    /* the following line can be commented out because PTHREAD_MUTEX_STALLED is
     * the default value for a mutex attribute object */
    pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_STALLED);

    pthread_mutex_init(&lock, &attr);   /* initialize the lock */

    pthread_create(&lock_getter, NULL, original_owner_thread, NULL);
    sleep(2);   /* original_owner_thread should have exited now */

    printf("Attempting to acquire unlock robust mutex.\n");
    int ret_code = pthread_mutex_lock(&lock);
    if(EOWNERDEAD == ret_code) {
        printf("EOWNERDEAD returned. Make the mutex consistent now\n");
        pthread_mutex_consistent(&lock);
    }

    pthread_mutex_unlock(&lock);

    return 0;
}