Re: For review: pthread_setcancelstate.3

[Loic Domaigne <tech-Z4JMKDdsf89Wk0Htik3J/w@public.gmane.org>]

Hi Michael,

my review for pthread_setcancelstate(3).

Cheers,
Loïc.
--

> .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
> .\"     <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> .\"
> .\" 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 PTHREAD_SETCANCELSTATE 3 2008-11-14 "Linux" "Linux Programmer's Manual"
> .SH NAME
> pthread_setcancelstate, pthread_setcanceltype \-
> set cancelability state and type
> .SH SYNOPSIS
> .nf
> .B #include <pthread.h>
> 
> .BI "int pthread_setcancelstate(int " state ", int *" oldstate );
> .BI "int pthread_setcanceltype(int " type ", int *" oldtype );
> .sp
> Compile and link with \fI\-pthread\fP.
> .SH DESCRIPTION
> The
> .BR pthread_setcancelstate ()
> sets the cancelability state of the calling thread to the value
> given in
> .IR state .
> The previous cancelability state of the thread is returned
> in the buffer pointed to by
> .IR oldstate .
> The
> .I state
> argument must have one of the following values:
> .TP
> .B PTHREAD_CANCEL_ENABLE
> The thread is cancelable.
> This is the default cancelability state in all new threads,
> including the initial thread.
> The thread's cancelability type determines when a cancelable thread
> will respond to a cancellation request.
> .TP
> .B PTHREAD_CANCEL_DISABLE
> The thread is not cancelable.
> If a cancellation request is received,
> it is blocked until cancelability is enabled.
> .PP
> The
> .BR pthread_setcanceltype ()
> sets the cancelability type of the calling thread to the value
> given in
> .IR type .
> The previous cancelability type of the thread is returned
> in the buffer pointed to by
> .IR oldtype .
> The
> .I type
> argument must have one of the following values:
> .TP
> .B PTHREAD_CANCEL_DEFERRED
> A cancellation request is deferred until the thread next calls
> a function that is a cancellation point (see
> .BR pthreads (7)).
> This is the default cancelability type in all new threads,
> including the initial thread.
> .TP
> .B PTHREAD_CANCEL_ASYNCHRONOUS
> The thread can be canceled at any time.
> (Typically,
> it will be canceled immediately upon receiving a cancellation request,
> but the system doesn't guarantee this.)
> .PP
> The set-and-get operation performed by each of these functions
> is atomic with respect to other threads in the process
> calling the same function.
> .SH RETURN VALUE
> On success, these functions return 0;
> on error, they return a non-zero error number.
> .SH ERRORS
> The
> .BR pthread_setcancelstate ()
> can fail with the following error:
> .TP
> .B EINVAL
> Invalid value for
> .IR state .
> .PP
> The
> .BR pthread_setcanceltype ()
> can fail with the following error:
> .TP
> .B EINVAL
> Invalid value for
> .IR type .
> .\" .SH VERSIONS
> .\" Available since glibc 2.0
> .SH CONFORMING TO
> POSIX.1-2001.
> .SH NOTES
> For details of what happens when a thread is canceled, see
> .BR pthread_cancel (3).
> 
> Briefly disabling cancelability is useful
> if a thread performs some critical action
> that must not be interrupted by a cancellation request.
> Beware of disabling cancelability for long periods,
> or around operations that may block for long periods,
> since that will render the thread unresponsive to cancellation requests.
> 
> Setting the cancelability type to
> .B PTHREAD_CANCEL_ASYNCHRONOUS
> is rarely useful.
> Since the thread could be canceled at
> .I any
> time, it cannot reserve resources (e.g., allocating memory),
> acquire mutexes, semaphores, or locks, and so on,
> since, when the thread is canceled,
> the application has no way of knowing what the state of these resources is;
> that is, did the canceled thread manage to release the resources or not?
> (Among other things, this means that clean-up handlers cease to be useful,
> since they can't determine the state of resources that
> they are intended to clean up.)
> In general, most library functions, including most pthreads functions,
> can't be safely called from an asynchronously cancelable thread.
> (POSIX.1-2001 only requires that
> .BR pthread_cancel (3),
> .BR pthread_setcancelstate (),
> and
> .BR pthread_setcanceltype ()
> be safe to call from an asynchronously cancelable thread.)
> One of the few circumstances in which asynchronous cancelability is useful
> is for cancellation of a thread that is in a pure compute-bound loop.

The paragraph is important, but I found it somewhat difficult to read. I 
don't pretend to compete with a native speaker, but find below a 
reworked version:

Setting the cancelability type to *PTHREAD_CANCEL_ASYNCHRONOUS* is 
rarely useful. The cancelation could occur at any time, for instance in 
a middle of a library call, like malloc(), leaving possibly inconsistent 
state. The application is not aware of those internal library states, 
and as no possibly to recover from possible inconsistencies. That is, 
clean-up handlers cease to be useful.  Functions that can be safely 
asynchronously canceled are called async-cancel-safe functions. 
POSIX.1-2001 only requires pthread_cancel(3), pthread_setcancelstate(3) 
and pthread_setcanceltype(3) to be async-cancel-safe. One of the few 
circumstances in which asynchronous cancelability is useful is for 
cancellation of a thread that is in a pure compute-bound loop.


> The Linux threading implementations permit the
> .I oldstate
> argument of
> .BR pthread_setcancelstate ()
> to be NULL, in which case the information about the previous
> cancelability state is not returned to the caller.
> Many other implementations also permit a NULL
> .I oldstat
> argument,
> .\" It looks like at least Solaris, FreeBSD and Tru64 support this.
> but POSIX.1-2001 does not specify this point,
> so portable applications should always specify a non-NULL value in
> .IR oldstate .
> A precisely analogous set of statements applies for the
> .I oldtype
> argument of
> .BR pthread_setcanceltype ().
> .SH EXAMPLE
> See
> .BR pthread_cancel (3).
> .SH SEE ALSO
> .BR pthread_cleanup_push (3),
> .BR pthread_cancel (3),
> .BR pthread_testcancel (3),
> .BR pthreads (7)
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html