GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:pthread_mutexattr_setrobust_np

PTHREAD_MUTEXATTR_SETROBUSTLinux Programmer's MaPTHREAD_MUTEXATTR_SETROBUST(3)

NAME

     pthread_mutexattr_getrobust,  pthread_mutexattr_setrobust - get and set
     the robustness attribute of a mutex attributes 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);
     Compile and link with -pthread.
 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
     pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust():
         _POSIX_C_SOURCE >= 200809L

DESCRIPTION

     The pthread_mutexattr_getrobust() function  places  the  value  of  the
     robustness attribute of the mutex attributes object referred to by attr
     in *robustness.  The pthread_mutexattr_setrobust()  function  sets  the
     value  of  the  robustness  attribute  of  the  mutex attributes object
     referred to by attr to the value specified in *robustness.
     The robustness attribute specifies the behavior of the mutex  when  the
     owning  thread  dies without unlocking the mutex.  The following values
     are valid for robustness:
     PTHREAD_MUTEX_STALLED
            This is the default value for a mutex attributes object.   If  a
            mutex  is  initialized  with the PTHREAD_MUTEX_STALLED attribute
            and its owner dies  without  unlocking  it,  the  mutex  remains
            locked    afterwards   and   any   future   attempts   to   call
            pthread_mutex_lock(3) on the mutex will block indefinitely.
     PTHREAD_MUTEX_ROBUST
            If  a  mutex  is  initialized  with   the   PTHREAD_MUTEX_ROBUST
            attribute  and  its  owner dies without unlocking it, any future
            attempts to call pthread_mutex_lock(3) on this mutex  will  suc-
            ceed  and  return EOWNERDEAD to indicate that the original owner
            no longer exists and the mutex  is  in  an  inconsistent  state.
            Usually 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    unlocks    the    mutex    using
            pthread_mutex_unlock(3) before making it consistent,  the  mutex
            will be permanently unusable and any subsequent attempts to lock
            it using pthread_mutex_lock(3) will fail with the error  ENOTRE-
            COVERABLE.   The  only  permitted  operation  on such a mutex is
            pthread_mutex_destroy(3).
            If the next owner terminates before  calling  pthread_mutex_con-
            sistent(3),  further  pthread_mutex_lock(3)  operations  on this
            mutex will still return EOWNERDEAD.
     Note  that  the  attr  argument  of  pthread_mutexattr_getrobust()  and
     pthread_mutexattr_setrobust() should refer to a mutex attributes object
     that was initialized by pthread_mutexattr_init(3), otherwise the behav-
     ior is undefined.

RETURN VALUE

     On success, these functions return 0.  On error, they return a positive
     error number.
     In  the  glibc  implementation,  pthread_mutexattr_getrobust()   always
     return zero.

ERRORS

     EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST
            was passed to pthread_mutexattr_setrobust().

VERSIONS

     pthread_mutexattr_getrobust()  and  pthread_mutexattr_setrobust()  were
     added to glibc in version 2.12.

CONFORMING TO

     POSIX.1-2008.

NOTES

     In  the Linux implementation, when using process-shared robust mutexes,
     a waiting thread also receives the EOWNERDEAD notification if the owner
     of  a  robust  mutex  performs an execve(2) without first unlocking the
     mutex.  POSIX.1 does not specify this detail,  but  the  same  behavior
     also occurs in at least some other implementations.
     Before the addition of pthread_mutexattr_getrobust() and pthread_mutex-
     attr_setrobust() to POSIX, glibc defined the following equivalent  non-
     standard functions if _GNU_SOURCE was defined:
     int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr,
                                        int *robustness);
     int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr,
                                        int robustness);
     Correspondingly,    the    constants    PTHREAD_MUTEX_STALLED_NP    and
     PTHREAD_MUTEX_ROBUST_NP were also defined.
     These GNU-specific APIs, which first appeared in glibc 2.4,  are  nowa-
     days obsolete and should not be used in new programs.

EXAMPLE

     The program below demonstrates the use of the robustness attribute of a
     mutex attributes object.  In this program, a thread holding  the  mutex
     dies  prematurely  without unlocking the mutex.  The main thread subse-
     quently acquires the mutex successfully and gets the error  EOWNERDEAD,
     after which it makes the mutex consistent.
     The  following  shell  session shows what we see when running this pro-
     gram:
         $  ./a.out  [original  owner]  Setting  lock...   [original  owner]
         Locked. Now exiting without unlocking.  [main thread] Attempting to
         lock the robust mutex.  [main thread] pthread_mutex_lock() returned
         EOWNERDEAD  [main  thread]  Now  make  the  mutex  consistent [main
         thread] Mutex is now consistent; unlocking
 Program source
     #include <stdlib.h> #include  <stdio.h>  #include  <unistd.h>  #include
     <pthread.h> #include <errno.h>
     #define handle_error_en(en, msg) \
                    do  {  errno  =  en;  perror(msg); exit(EXIT_FAILURE); }
     while (0)
     static pthread_mutex_t mtx;
     static void * original_owner_thread(void *ptr) {
         printf("[original owner] Setting lock...\n");
         pthread_mutex_lock(&mtx);
         printf("[original  owner]  Locked.  Now  exiting  without   unlock-
     ing.\n");
         pthread_exit(NULL); }
     int main(int argc, char *argv[]) {
         pthread_t thr;
         pthread_mutexattr_t attr;
         int s;
         pthread_mutexattr_init(&attr);
                                     /* initialize the attributes object */
         pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
                                    /* set robustness */
         pthread_mutex_init(&mtx, &attr);   /* initialize the mutex */
         pthread_create(&thr, NULL, original_owner_thread, NULL);
         sleep(2);
         /* "original_owner_thread" should have exited by now */
         printf("[main thread] Attempting to lock the robust mutex.\n");
         s = pthread_mutex_lock(&mtx);
         if (s == EOWNERDEAD) {
             printf("[main   thread]   pthread_mutex_lock()  returned  EOWN-
     ERDEAD\n");
             printf("[main thread] Now make the mutex consistent\n");
             s = pthread_mutex_consistent(&mtx);
             if (s != 0)
                 handle_error_en(s, "pthread_mutex_consistent");
             printf("[main thread] Mutex is now consistent; unlocking\n");
             s = pthread_mutex_unlock(&mtx);
             if (s != 0)
                 handle_error_en(s, "pthread_mutex_unlock");
             exit(EXIT_SUCCESS);
         } else if (s == 0) {
             printf("[main thread]  pthread_mutex_lock()  unexpectedly  suc-
     ceeded\n");
             exit(EXIT_FAILURE);
         } else {
             printf("[main    thread]    pthread_mutex_lock()   unexpectedly
     failed\n");
             handle_error_en(s, "pthread_mutex_lock");
         } }

SEE ALSO

     get_robust_list(2), set_robust_list(2), pthread_mutex_init(3),
     pthread_mutex_consistent(3), pthread_mutex_lock(3), pthreads(7)

COLOPHON

     This page is part of release 4.16 of the Linux man-pages project.  A
     description of the project, information about reporting bugs, and the
     latest version of this page, can be found at
     https://www.kernel.org/doc/man-pages/.

Linux 2017-08-20 PTHREAD_MUTEXATTR_SETROBUST(3)

/data/webs/external/dokuwiki/data/pages/man/pthread_mutexattr_setrobust_np.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki