From patchwork Mon Aug 21 02:24:32 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yubin Ruan X-Patchwork-Id: 22251 Received: (qmail 121777 invoked by alias); 21 Aug 2017 02:25:38 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 117087 invoked by uid 89); 21 Aug 2017 02:25:12 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.4 required=5.0 tests=BAYES_00, FREEMAIL_FROM, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, RCVD_IN_SORBS_SPAM, SPF_PASS autolearn=ham version=3.3.2 spammy=ALSO, damages, unusable, omissions X-HELO: mail-wr0-f194.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=wo2XntWbou1kx5aCA0/Zl152Y9lpMmpGsjj1kT5bIkc=; b=SSt9zddruelDwxH1OyvyPSU9xxxR9szE6LM9dU7WNGY6rrwnI/mBV7EhapK3daT09m JHpF5RflTXQwb4KNMar/7IE2QjKY6yF3c8qYyBy1cZSroigX9Jy6nXYaOWHSBGjQceG2 p68hYGqxLdSs0bh3gWdlBUKknMsdk2hTs+RBDcs4regfvY8yq1dObRFofsX+zJad7Kfz r1IGmo2ivfWSIAUioh0VsM4KpnEmc+MWbdgQCrxPQzYh3EmCaqVeAkjks4LvHRbCKmfk tBBELcBDkziWTHv33lH4Ld+VEROKbH/HUvSq5Q9RnhtSUncP4uGuVdbQsIqMUGI7ONkC 4PsQ== X-Gm-Message-State: AHYfb5idio6cuZa4WCPIhoPorQLEwDt9P2UHwL/bK2EVfEoWVdvLsKLj irOZFzrSGbjMM+4IAxhlcc31CkZAiA== X-Received: by 10.80.148.211 with SMTP id t19mr11394356eda.128.1503282273080; Sun, 20 Aug 2017 19:24:33 -0700 (PDT) MIME-Version: 1.0 In-Reply-To: References: From: Yubin Ruan Date: Mon, 21 Aug 2017 10:24:32 +0800 Message-ID: Subject: Re: [PATCTH 0/2] pthread_mutexattr_setrobust() and pthread_mutex_consistent() To: "Michael Kerrisk (man-pages)" Cc: linux-man@vger.kernel.org, libc-alpha@sourceware.org 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 Date: Mon, 21 Aug 2017 00:23:03 +0800 Subject: [PATCH] add pthread_mutexattr_setrobust() and pthread_mutex_consistent() Signed-off-by: Yubin Ruan --- 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) diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3 new file mode 100644 index 0000000..6d5bc81 --- /dev/null +++ b/man3/pthread_mutex_consistent.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" +.\" %%%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 +.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) diff --git a/man3/pthread_mutexattr_setrobust.3 b/man3/pthread_mutexattr_setrobust.3 new file mode 100644 index 0000000..e44e590 --- /dev/null +++ b/man3/pthread_mutexattr_setrobust.3 @@ -0,0 +1,199 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" +.\" %%%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 +.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 +#include +#include +#include + +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