lkml.org 
[lkml]   [2008]   [Dec]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    Subject[PATCH v2] add man-page for pthread_mutexattr_setrobust_np()
    * Michael Kerrisk | 2008-12-07 11:44:54 [-0500]:

    >Sebastian,
    Michael,

    >I will have more comments later, but a few quick comments now. Could
    >you revise your page in the light of these comments?
    Yup. Here is version two. I somehow mixed up the IEEE man-pages with
    yours. So first I didn't understand most of you comments :) Once I
    figured that out I tried to address all of your comments and I've also
    rephrased everything. Be prepared :)

    Signed-off-by: Sebastian Andrzej Siewior <sebastian@breakpoint.cc>
    ---
    man3/pthread_mutex_consistent_np.3 | 1 +
    man3/pthread_mutexattr_getrobust_np.3 | 1 +
    man3/pthread_mutexattr_setrobust_np.3 | 255 +++++++++++++++++++++++++++++++++
    3 files changed, 257 insertions(+), 0 deletions(-)
    create mode 100644 man3/pthread_mutex_consistent_np.3
    create mode 100644 man3/pthread_mutexattr_getrobust_np.3
    create mode 100644 man3/pthread_mutexattr_setrobust_np.3

    diff --git a/man3/pthread_mutex_consistent_np.3 b/man3/pthread_mutex_consistent_np.3
    new file mode 100644
    index 0000000..a92edb9
    --- /dev/null
    +++ b/man3/pthread_mutex_consistent_np.3
    @@ -0,0 +1 @@
    +.so man3/pthread_mutexattr_setrobust_np.3
    diff --git a/man3/pthread_mutexattr_getrobust_np.3 b/man3/pthread_mutexattr_getrobust_np.3
    new file mode 100644
    index 0000000..a92edb9
    --- /dev/null
    +++ b/man3/pthread_mutexattr_getrobust_np.3
    @@ -0,0 +1 @@
    +.so man3/pthread_mutexattr_setrobust_np.3
    diff --git a/man3/pthread_mutexattr_setrobust_np.3 b/man3/pthread_mutexattr_setrobust_np.3
    new file mode 100644
    index 0000000..34dbd6e
    --- /dev/null
    +++ b/man3/pthread_mutexattr_setrobust_np.3
    @@ -0,0 +1,255 @@
    +.\" Copyright (c) 2008 Sebastian Andrzej Siewior
    +.\" Copyright (c) 2008 Linux Foundation, Michael Kerrisk
    +.\" <mtk.manpages@gmail.com>
    +.\"
    +.\" Permission is granted to make and distribute verbatim copies of this
    +.\" manual provided the copyright notice and this permission notice are
    +.\" preserved on all copies.
    +.\"
    +.\" Permission is granted to copy and distribute modified versions of this
    +.\" manual under the conditions for verbatim copying, provided that the
    +.\" entire resulting derived work is distributed under the terms of a
    +.\" permission notice identical to this one.
    +.\"
    +.\" Since the Linux kernel and libraries are constantly changing, this
    +.\" manual page may be incorrect or out-of-date. The author(s) assume no
    +.\" responsibility for errors or omissions, or for damages resulting from
    +.\" the use of the information contained herein. The author(s) may not
    +.\" have taken the same level of care in the production of this manual,
    +.\" which is licensed free of charge, as they might when working
    +.\" professionally.
    +.\"
    +.\" Formatted or processed versions of this manual, if unaccompanied by
    +.\" the source, must acknowledge the copyright and authors of this work.
    +
    +.TH "ROBUST MUTEXES" 3 2008-12-18 "GNU C Library" "Linux Programmer's Manual"
    +.SH NAME
    +pthread_mutexattr_setrobust_np, pthread_mutexattr_getrobust_np \- set or get
    +the robustness of a mutex.
    +.SH SYNOPSIS
    +.nf
    +.B #define _GNU_SOURCE
    +.B #include <pthread.h>
    +.sp
    +.BI "int pthread_mutexattr_getrobust_np(pthread_mutexattr_t " *attr ",
    +.BI " int " robustness ");"
    +.BI "int pthread_mutexattr_setrobust_np(pthread_mutexattr_t " *attr ",
    +.BI " int " robustness ");"
    +.BI "int pthread_mutex_consistent_np(pthread_mutex_t " *mutex ");"
    +.fi
    +.sp
    +Compile and link with \fI\-pthread\fP.
    +.SH DESCRIPTION
    +The
    +.BR pthread_mutexattr_getrobust_np ()
    +sets the robustness of the mutex attribute object referred to by
    +.I attr
    +to the value specified in
    +.IR robustness .
    +The
    +.BR pthread_mutexattr_getrobust_np ()
    +retrieves the current values of robustness of mutex attribute object referred
    +to by
    +.IR attr .
    +The following values may be specified in
    +.IR robustness :
    +.TP
    +.B PTHREAD_MUTEX_STALLED_NP
    +Mutexes created using
    +.I attr
    +will stall if the owner dies while owning the lock.
    +.PP
    +The default setting of the robustness attribute in a newly initialized mutex
    +object is
    +.BR PTHREAD_MUTEX_STALLED_NP .
    +.TP
    +.B PTHREAD_MUTEX_ROBUST_NP
    +Mutexes created using
    +.I attr
    +will be reboots. If the owner dies while holding the lock
    +.BR pthread_mutex_lock ()
    +will return
    +.BR EOWNERDEAD
    +.B and
    +the caller is holding lock.
    +This return value shall signalize the caller that the resource which is
    +protected by the mutex may be in an inconsistent state and should be verified
    +before used.
    +Once the lock holder sanitized the protected resource he should invoke
    +.BR pthread_mutex_consistent_np ()
    +on the mutex object to mark that mutex as consistent.
    +If this is not done, future locking requests will return
    +.B EOWNERDEAD
    +although the previous owner did not die.
    +.SH "RETURN VALUE"
    +On success, these functions return 0;
    +on error, they return a non-zero error number.
    +.SH ERRORS
    +.BR pthread_mutexattr_setrobust_np ()
    +can fail with the following error:
    +.TP
    +.B EINVAL
    +Invalid value in
    +.IR robustness .
    +.PP
    +.BR pthread_mutexattr_getrobust_np ()
    +can fail with the following error:
    +.TP
    +.B EINVAL
    +Invalid value in
    +.IR robustness .
    +.PP
    +.BR pthread_mutex_consistent_np ()
    +can fail with the following error:
    +.TP
    +.B EINVAL
    +The mutex object specified by
    +.I mutex
    +is either not
    +.B PTHREAD_MUTEX_ROBUST_NP
    +or is in a consistent state.
    +.PP
    +.SH EXAMPLE
    +The code example shows how to share a lock between two applications without
    +System V IPC.
    +An advantage over System V semaphores is that the kernel is not invoked in
    +case the lock is not hold.
    +If one of the applications dies while holding the lock or the system reboots
    +unexpectedly, the new owner of lock marks the lock state consistent.
    +In this example the lock owner does not need to perform any validation of the
    +resource protected by the lock.
    +
    +.nf
    +#define _GNU_SOURCE
    +
    +#include <errno.h>
    +#include <fcntl.h>
    +#include <pthread.h>
    +#include <stdio.h>
    +#include <stdlib.h>
    +#include <string.h>
    +#include <unistd.h>
    +
    +#include <sys/mman.h>
    +#include <sys/stat.h>
    +#include <sys/types.h>
    +
    +static const char *lock_name = "/dev/shm/limi_lock";
    +static pthread_mutex_t *limi_mutex;
    +
    +static int open_existing_lock(void)
    +{
    + int fd;
    + int ret;
    + struct stat buf;
    + int retry = 5;
    +
    + fd = open(lock_name, O_RDWR);
    + if (fd < 0)
    + return fd;
    + do {
    + ret = fstat(fd, &buf);
    + if (ret < 0)
    + return ret;
    +
    + if (buf.st_size == sizeof(*limi_mutex))
    + return fd;
    +
    + close(fd);
    + sleep(1);
    + retry\-\-;
    + } while (retry);
    +
    + close(fd);
    + return \-1;
    +}
    +
    +static int create_new_lock(void)
    +{
    + int fd;
    + pthread_mutex_t cmutex = PTHREAD_MUTEX_INITIALIZER;
    + pthread_mutexattr_t attr;
    + int ret;
    +
    + pthread_mutexattr_init(&attr);
    + pthread_mutexattr_setrobust_np(&attr, PTHREAD_MUTEX_ROBUST_NP);
    + pthread_mutex_init(&cmutex, &attr);
    +
    + fd = open(lock_name, O_RDWR | O_CREAT | O_EXCL, S_IRUSR | S_IWUSR |
    + S_IRGRP | S_IWGRP);
    + if (fd < 0)
    + return fd;
    +
    + ret = write(fd, &cmutex, sizeof(cmutex));
    + if (ret < 0) {
    + fprintf(stderr, "Write to %s failed: %s\\n",
    + lock_name, strerror(errno));
    + exit(1);
    + }
    + return fd;
    +}
    +
    +void limi_lock_init(void)
    +{
    + void *limi_lock_mmap;
    + int lock_fd;
    +
    + lock_fd = open_existing_lock();
    + if (lock_fd < 0) {
    + lock_fd = create_new_lock();
    + if (lock_fd < 0) {
    + lock_fd = open_existing_lock();
    + if (lock_fd < 0) {
    + fprintf(stderr, "Can't open %s: %s\\n",
    + lock_name, strerror(errno));
    + exit(1);
    + }
    + }
    + }
    +
    + limi_lock_mmap = mmap(NULL, sizeof(*limi_mutex),
    + PROT_READ | PROT_WRITE, MAP_SHARED, lock_fd, 0);
    + close(lock_fd);
    + if (limi_lock_mmap == MAP_FAILED) {
    + fprintf(stderr, "failed to mmap limi lock: %s\\n",
    + strerror(errno));
    + exit(1);
    + }
    + limi_mutex = limi_lock_mmap;
    +}
    +
    +void limi_lock(void)
    +{
    + int ret;
    +
    + ret = pthread_mutex_lock(limi_mutex);
    + if (!ret)
    + return;
    +
    + if (ret == EOWNERDEAD) {
    + pthread_mutex_consistent_np(limi_mutex);
    + return;
    + }
    +
    + fprintf(stderr, "Can not grab lock: %s\\n", strerror(ret));
    + exit(1);
    +}
    +
    +void limi_unlock(void)
    +{
    + int ret;
    +
    + ret = pthread_mutex_unlock(limi_mutex);
    + if (!ret)
    + return;
    +
    + fprintf(stderr, "Can not unlock: %s\\n", strerror(ret));
    + exit(1);
    +}
    +
    +.fi
    +.SH "SEE ALSO"
    +.BR pthread_mutex_create (3),
    +.BR pthread_mutexattr_init (3),
    +.BR pthread_mutex_lock (3),
    +.BR pthread_mutex_unlock (3)
    --
    1.6.0.4


    \
     
     \ /
      Last update: 2008-12-21 22:03    [W:0.037 / U:30.104 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site