[PATCTH,0/2] pthread_mutexattr_setrobust() and pthread_mutex_consistent()
Commit Message
Hmm...My email system broke and all the mails were delayed. Here you go:
Below are patch generated by `git format-patch`. Also, please find
attached some verification code I wrote. I tended to write more, but I
would like to hear what people think about these first in case I am
not doing anything wrong in the first place.
Yubin
------------------------------------------------
From 29850aa815506e8a97fb9d90c71285161ee69d82 Mon Sep 17 00:00:00 2001
From: Yubin Ruan <ablacktshirt@gmail.com>
Date: Mon, 21 Aug 2017 00:23:03 +0800
Subject: [PATCH] add pthread_mutexattr_setrobust() and
pthread_mutex_consistent()
Signed-off-by: Yubin Ruan <ablacktshirt@gmail.com>
---
man3/pthread_mutex_consistent.3 | 60 +++++++++++
man3/pthread_mutexattr_setrobust.3 | 199 +++++++++++++++++++++++++++++++++++++
2 files changed, 259 insertions(+)
create mode 100644 man3/pthread_mutex_consistent.3
create mode 100644 man3/pthread_mutexattr_setrobust.3
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_mutex_init (3),
+.BR pthread_mutex_consistent (3),
+.BR pthread_mutex_lock (3)
+.BR pthreads (7)
Comments
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 ---
new file mode 100644
@@ -0,0 +1,60 @@
+.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" 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.
+.\" %%%LICENSE_END
+.\"
+.TH PTHREAD_MUTEXATTR_SETROBUST 3 2017-08-20 "Linux" "Linux
Programmer's Manual"
+.SH NAME
+pthread_mutex_consistent \- make the robust mutex consistent
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_mute_consistent(pthread_mute_t *" mutex ");"
+.fi
+.PP
+Compile and link with \fI\-pthread\fP.
+.SH 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
+.B EOWNERDEAD.
+
+.SH RETURN VALUE
+On success,
+.IR pthread_mutex_consistent()
+return 0. Otherwise an error value is returned to indicate the error.
+
+.SH ERRORS
+.TP
+.B EINVAL
+The mutex is either not robust or it is not in a inconsistent state.
+
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_mutexattr_init (3),
+.BR pthread_mutex_lock (3),
+.BR pthread_mutexattr_setrobust (3),
+.BR pthread_mutexattr_getrobust (3),
+.BR pthreads (7)
b/man3/pthread_mutexattr_setrobust.3
new file mode 100644
@@ -0,0 +1,199 @@
+.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" 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.
+.\" %%%LICENSE_END
+.\"
+.TH PTHREAD_MUTEXATTR_SETROBUST 3 2017-08-20 "Linux" "Linux
Programmer's Manual"
+.SH 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
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *"
attr, "int *" robustness ");"
+.BI "int pthread_mutexattr_setrobust(const pthread_mutexattr_t *"
attr, "int *" robustness ");"
+.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *"
attr, "int *" robustness ");"
+.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *"
attr, "int *" robustness ");"
+.fi
+.PP
+Compile and link with \fI\-pthread\fP.
+.SH DESCRIPTION
+The
+.BR pthread_mutexattr_getrobust()
+and
+.BR 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
+.BR pthread_mutexattr_getrobust_np (3)
+and
+.BR pthread_mutexattr_setrobust_np (3)
+respectively but they are just aliases, with the "np" standing for
"Native Posix".
+See
+.BR NPTL (7).
+.PP
+Currently there are only two possible values for the
+.IR robustness
+attribute:
+.TP
+.BR PTHREAD_MUTEX_STALLED
+is the default value for a mutex attribute object. If a mutex is initialized
+with a
+.BR PTHREAD_MUTEX_STALLED
+attribute object and its owner dies without unlocking it, it is kept locked
+afterwards and any future attempts to call
+.IR pthread_mutex_lock (3)
+on this mutex will block indefinitely.
+.TP
+.B 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
+.IR execve (2)
+, any future attempts to call
+.IR pthread_mutex_lock (3)
+on this mutex will suceed and return
+.B EOWNERDEAD
+to indicate that the original owner no longer exists and the mutex is left in
+an inconsisten state. Usually after
+.B EOWNERDEAD
+is returned, the next owner should call
+.IR pthread_mutex_consistent (3)
+on the acquired mutex to make it consistent again before using it any further.
+If the next owner unlock it using
+.IR pthread_mutex_unlock (3)
+before making it consistent, the mutex will be unusable permanently and any
+subsequent attempts to lock it using
+.IR pthread_mutex_lock (3)
+will return
+.B ENORECOVERABLE.
+If the next owner terminates before calling
+.IR pthread_mutex_consistent (3)
+, furture
+.IR pthread_mutex_lock (3)
+on this mutex will still return
+.B EOWNERDEAD.
+
+
+Glibc defined
+.B PTHREAD_MUTEX_STALLED_NP
+and
+.B PTHREAD_MUTEX_ROBUST_NP
+as aliases of
+.B PTHREAD_MUTEX_STALLED
+and
+.B PTHREAD_MUTEX_ROBUST
+respectively.
+
+Note that the
+.IR attr
+argument of
+.IR pthread_mutexattr_getrobust()
+and
+.IR pthread_mutexattr_setrobust()
+should refer to a mutex attribute object that was initialized by
+.IR pthread_mutexattr_init (3)
+, otherwise the behavior is undefined.
+.SH RETURN VALUE
+On success, zero is returned by
+.IR pthread_mutexattr_getrobust()
+and the value pointed to by the
+.IR robustness
+parameter is set to the robustness attribute of
+.IR attr.
+Otherwise, an error number shall be returned. On success
+.IR pthread_mutexattr_setrobust()
+set the robustness attribute into the mutex attribute object
+.IR attr
+and return zero, otherwise a error number is returned to indicate the error.
+.SS Glibc-specificed features
+In glibc's implementation,
+.IR pthread_mutexattr_getrobust()
+always return zero.
+.SH ERRORS
+.TP
+.B EINVAL
+A value other than
+.B PTHREAD_MUTEX_STALLED
+or
+.B PTHREAD_MUTEX_ROBUST
+is passed into
+.IR pthread_mutexattr_setrobust().
+
+.SH EXAMPLE
+The program demonstrate a simple usecase of the robustness attribute of a
+pthread mutex attribute object. In this program, a thread holding the mutex
+die prematurely withough unlocking the mutex. Another thread acquire it
+successfully and get EOWNERDEAD.
+
+.SS Program source
+\&
+.EX
+#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;
+}
+.EE