For review: pthread_cleanup_push.3

For review: pthread_cleanup_push.3

[Michael Kerrisk]

Any reviewer for pthread_cleanup_push(3)?

Cheers,

Michael

.\" 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_CLEANUP_PUSH 3 2008-11-14 "Linux" "Linux Programmer's Manual"
.SH NAME
pthread_cleanup_push, pthread_cleanup_pop \- push and pop
thread cancellation clean-up handlers
.SH SYNOPSIS
.nf
.B #include <pthread.h>

.BI "void pthread_cleanup_push(void (*" routine ")(void *),"
.BI "                          void *" arg );
.BI "void pthread_cleanup_pop(int " execute );
.sp
Compile and link with \fI\-pthread\fP.
.SH DESCRIPTION
These functions manipulate the calling thread's stack of
thread-cancellation clean-up handlers.
A clean-up handler is a function that is automatically executed
when a thread is canceled (or in various other circumstances
described below);
it might, for example, unlock a mutex so that
it becomes available to other threads in the process.

The
.BR pthread_cleanup_push ()
function pushes
.I routine
onto the top of the stack of clean-up handlers.
When
.I routine
is later invoked, it will be given
.I arg
as its argument.

The
.BR pthread_cleanup_pop ()
function removes the routine at the top of the stack of clean-up handlers,
and optionally executes it if
.I execute
is non-zero.

A cancellation clean-up handler is popped from the stack
and executed in the following circumstances:
.IP 1. 3
When a thread is canceled,
all of the stacked clean-up handlers are popped and executed in
the reverse of the order in which they were pushed onto the stack.
.IP 2.
When a thread terminates by calling
.BR pthread_exit (3),
all clean-up handlers are executed as described in the preceding point.
(Clean-up handlers are \fInot\fP called if the thread terminates by
performing a
.I return
from the thread start function.)
.IP 3.
When a thread calls
.BR pthread_cleanup_pop ()
with a non-zero
.I execute
argument, the top-most clean-up handler is popped and executed.
.PP
POSIX.1 permits
.BR pthread_cleanup_push ()
and
.BR pthread_cleanup_pop ()
to be implemented as macros that expand to text
containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
For this reason, the caller must ensure that calls to these
functions are paired within the same function,
and at the same lexical nesting level.
(In other words, a clean-up handler is only established
during the execution of a specified section of code.)

Calling
.BR longjmp (3)
.RB ( siglongjmp (3))
produces undefined results if any call has been made to
.BR pthread_cleanup_push ()
or
.BR pthread_cleanup_pop ()
without the matching call of the pair since the jump buffer
was filled by
.BR setjmp (3)
.RB ( sigsetjmp (3)).
Likewise, calling
.BR longjmp (3)
.RB ( siglongjmp (3))
from inside a clean-up handler produces undefined results
unless the jump buffer was also filled by
.BR setjmp (3)
.RB ( sigsetjmp (3))
inside the handler.
.SH RETURN VALUE
These functions do not return a value.
.SH ERRORS
There are no errors.
.\" SH VERSIONS
.\" Available since glibc 2.0
.SH CONFORMING TO
POSIX.1-2001.
.SH NOTES
On Linux, the
.BR pthread_cleanup_push ()
and
.BR pthread_cleanup_pop ()
functions \fIare\fP implemented as macros that expand to text
containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
This means that variables declared within the scope of
paired calls to these functions will only be visible within that scope.
.SH EXAMPLE
The program below provides a simple example of the use of the functions
described in this page.
The program creates a thread that executes a loop bracketed by
.BR pthread_cleanup_push ()
and
.BR pthread_cleanup_pop ().
This loop executes a global variable,
.IR cnt ,
once each second.
Depending on what command-line arguments are supplied,
the main thread sends the other thread a cancellation request,
or sets a global variable that causes the other thread
to exit its loop and terminate normally (by doing a
.IR return ).

In the following shell session,
the main thread sends a cancellation request to the other thread:

.in +4n
.nf
$ \fB./a.out\fP
New thread started
cnt = 0
cnt = 1
Canceling thread
Called clean-up handler
Thread was canceled; cnt = 0
.fi
.in

>From the above, we see that the thread was canceled,
and that the cancellation clean-up handler was called
and it reset the value of the global variable
.I cnt
to 0.

In the next run, the main program sets a
global variable that causes other thread to terminate normally:

.in +4n
.nf
$ \fB./a.out x\fP
New thread started
cnt = 0
cnt = 1
Thread terminated normally; cnt = 2
.fi
.in

>From the above, we see that the clean-up handler was not executed (because
.I cleanup_pop_arg
was 0), and therefore the value of
.I cnt
was not reset.

In the next run, the main program sets a global variable that
causes the other thread to terminate normally,
and supplies a non-zero value for
.IR cleanup_pop_arg :

.in +4n
.nf
$ \fB./a.out x 1\fP
New thread started
cnt = 0
cnt = 1
Called clean-up handler
Thread terminated normally; cnt = 0
.fi
.in

In the above, we see that although the thread was not canceled,
the clean-up handler was executed, because the argument given to
.BR pthread_cleanup_pop ()
was non-zero.
.SS Program source
\&
.nf
#include <pthread.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>

#define handle_error_en(en, msg) \\
        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

static int done = 0;
static int cleanup_pop_arg = 0;
static int cnt = 0;

static void
cleanup_handler(void *arg)
{
    printf("Called clean\-up handler\\n");
    cnt = 0;
}

static void *
thread_start(void *arg)
{
    time_t start, curr;

    printf("New thread started\\n");

    pthread_cleanup_push(cleanup_handler, NULL);

    curr = start = time(NULL);

    while (!done) {
        pthread_testcancel();           /* A cancellation point */
        if (curr < time(NULL)) {
            curr = time(NULL);
            printf("cnt = %d\\n", cnt);  /* A cancellation point */
            cnt++;
        }
    }

    pthread_cleanup_pop(cleanup_pop_arg);
    return NULL;
}

int
main(int argc, char *argv[])
{
    pthread_t thr;
    int s;
    void *res;

    s = pthread_create(&thr, NULL, thread_start, (void *) 1);
    if (s != 0)
        handle_error_en(s, "pthread_create");

    sleep(2);           /* Allow new thread to run a while */

    if (argc > 1) {
        if (argc > 2)
            cleanup_pop_arg = atoi(argv[2]);
        done = 1;

    } else {
        printf("Canceling thread\\n");
        s = pthread_cancel(thr);
        if (s != 0)
            handle_error_en(s, "pthread_cancel");
    }

    s = pthread_join(thr, &res);
    if (s != 0)
        handle_error_en(s, "pthread_join");

    if (res == PTHREAD_CANCELED)
        printf("Thread was canceled; cnt = %d\\n", cnt);
    else
        printf("Thread terminated normally; cnt = %d\\n", cnt);
    exit(EXIT_SUCCESS);
}
.fi
.SH SEE ALSO
.BR pthread_cancel (3),
.BR pthread_cleanup_push_defer_np (3),
.BR pthread_setcancelstate (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

Re: For review: pthread_cleanup_push.3

[Loic Domaigne]

Hi Michael,

the last review for today.

Bye for now,
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_CLEANUP_PUSH 3 2008-11-14 "Linux" "Linux Programmer's Manual"
> .SH NAME
> pthread_cleanup_push, pthread_cleanup_pop \- push and pop
> thread cancellation clean-up handlers
> .SH SYNOPSIS
> .nf
> .B #include <pthread.h>
> 
> .BI "void pthread_cleanup_push(void (*" routine ")(void *),"
> .BI "                          void *" arg );
> .BI "void pthread_cleanup_pop(int " execute );
> .sp
> Compile and link with \fI\-pthread\fP.
> .SH DESCRIPTION
> These functions manipulate the calling thread's stack of
> thread-cancellation clean-up handlers.
> A clean-up handler is a function that is automatically executed
> when a thread is canceled (or in various other circumstances
> described below);
> it might, for example, unlock a mutex so that
> it becomes available to other threads in the process.
> 
> The
> .BR pthread_cleanup_push ()
> function pushes
> .I routine
> onto the top of the stack of clean-up handlers.
> When
> .I routine
> is later invoked, it will be given
> .I arg
> as its argument.
> 
> The
> .BR pthread_cleanup_pop ()
> function removes the routine at the top of the stack of clean-up handlers,
> and optionally executes it if
> .I execute
> is non-zero.
> 
> A cancellation clean-up handler is popped from the stack
> and executed in the following circumstances:
> .IP 1. 3
> When a thread is canceled,
> all of the stacked clean-up handlers are popped and executed in
> the reverse of the order in which they were pushed onto the stack.
> .IP 2.
> When a thread terminates by calling
> .BR pthread_exit (3),
> all clean-up handlers are executed as described in the preceding point.
> (Clean-up handlers are \fInot\fP called if the thread terminates by
> performing a
> .I return
> from the thread start function.)

Generally speaking, it is left to the implementation to call or not
clean-up handlers when a thread returns from the start function.

The behavior you are describing is Linux specific; so perhaps you should 
put this in the NOTE, in the same way that you mentioned that 
pthread_cleanup_{push/pop} are macro on Gnu/Linux.

> .IP 3.
> When a thread calls
> .BR pthread_cleanup_pop ()
> with a non-zero
> .I execute
> argument, the top-most clean-up handler is popped and executed.
> .PP
> POSIX.1 permits
> .BR pthread_cleanup_push ()
> and
> .BR pthread_cleanup_pop ()
> to be implemented as macros that expand to text
> containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
> For this reason, the caller must ensure that calls to these
> functions are paired within the same function,
> and at the same lexical nesting level.
> (In other words, a clean-up handler is only established
> during the execution of a specified section of code.)
> 
> Calling
> .BR longjmp (3)
> .RB ( siglongjmp (3))
> produces undefined results if any call has been made to
> .BR pthread_cleanup_push ()
> or
> .BR pthread_cleanup_pop ()
> without the matching call of the pair since the jump buffer
> was filled by
> .BR setjmp (3)
> .RB ( sigsetjmp (3)).
> Likewise, calling
> .BR longjmp (3)
> .RB ( siglongjmp (3))
> from inside a clean-up handler produces undefined results
> unless the jump buffer was also filled by
> .BR setjmp (3)
> .RB ( sigsetjmp (3))
> inside the handler.
> .SH RETURN VALUE
> These functions do not return a value.
> .SH ERRORS
> There are no errors.
> .\" SH VERSIONS
> .\" Available since glibc 2.0
> .SH CONFORMING TO
> POSIX.1-2001.
> .SH NOTES
> On Linux, the
> .BR pthread_cleanup_push ()
> and
> .BR pthread_cleanup_pop ()
> functions \fIare\fP implemented as macros that expand to text
> containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
> This means that variables declared within the scope of
> paired calls to these functions will only be visible within that scope.
> .SH EXAMPLE
> The program below provides a simple example of the use of the functions
> described in this page.
> The program creates a thread that executes a loop bracketed by
> .BR pthread_cleanup_push ()
> and
> .BR pthread_cleanup_pop ().
> This loop executes a global variable,
> .IR cnt ,
> once each second.

s/executes/increments/

> Depending on what command-line arguments are supplied,
> the main thread sends the other thread a cancellation request,
> or sets a global variable that causes the other thread
> to exit its loop and terminate normally (by doing a
> .IR return ).
> 
> In the following shell session,
> the main thread sends a cancellation request to the other thread:
> 
> .in +4n
> .nf
> $ \fB./a.out\fP
> New thread started
> cnt = 0
> cnt = 1
> Canceling thread
> Called clean-up handler
> Thread was canceled; cnt = 0
> .fi
> .in
> 
>>From the above, we see that the thread was canceled,

garbage '>' ?

> and that the cancellation clean-up handler was called
> and it reset the value of the global variable
> .I cnt
> to 0.
> 
> In the next run, the main program sets a
> global variable that causes other thread to terminate normally:
> 
> .in +4n
> .nf
> $ \fB./a.out x\fP
> New thread started
> cnt = 0
> cnt = 1
> Thread terminated normally; cnt = 2
> .fi
> .in
> 
>>From the above, we see that the clean-up handler was not executed (because

garbage '>' ?

> .I cleanup_pop_arg
> was 0), and therefore the value of
> .I cnt
> was not reset.
> 
> In the next run, the main program sets a global variable that
> causes the other thread to terminate normally,
> and supplies a non-zero value for
> .IR cleanup_pop_arg :
> 
> .in +4n
> .nf
> $ \fB./a.out x 1\fP
> New thread started
> cnt = 0
> cnt = 1
> Called clean-up handler
> Thread terminated normally; cnt = 0
> .fi
> .in
> 
> In the above, we see that although the thread was not canceled,
> the clean-up handler was executed, because the argument given to
> .BR pthread_cleanup_pop ()
> was non-zero.
> .SS Program source
> \&
> .nf
> #include <pthread.h>
> #include <sys/types.h>
> #include <stdio.h>
> #include <stdlib.h>
> #include <unistd.h>
> #include <errno.h>
> 
> #define handle_error_en(en, msg) \\
>         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
> 
> static int done = 0;
> static int cleanup_pop_arg = 0;
> static int cnt = 0;
> 
> static void
> cleanup_handler(void *arg)
> {
>     printf("Called clean\-up handler\\n");
>     cnt = 0;
> }
> 
> static void *
> thread_start(void *arg)
> {
>     time_t start, curr;
> 
>     printf("New thread started\\n");
> 
>     pthread_cleanup_push(cleanup_handler, NULL);
> 
>     curr = start = time(NULL);
> 
>     while (!done) {
>         pthread_testcancel();           /* A cancellation point */
>         if (curr < time(NULL)) {
>             curr = time(NULL);
>             printf("cnt = %d\\n", cnt);  /* A cancellation point */

printf() is not a mandatory CP (but is a CP on Linux).

>             cnt++;
>         }
>     }
> 
>     pthread_cleanup_pop(cleanup_pop_arg);
>     return NULL;
> }
> 
> int
> main(int argc, char *argv[])
> {
>     pthread_t thr;
>     int s;
>     void *res;
> 
>     s = pthread_create(&thr, NULL, thread_start, (void *) 1);

Why (void*) 1 as arg?

>     if (s != 0)
>         handle_error_en(s, "pthread_create");
> 
>     sleep(2);           /* Allow new thread to run a while */
> 
>     if (argc > 1) {
>         if (argc > 2)
>             cleanup_pop_arg = atoi(argv[2]);
>         done = 1;
> 
>     } else {
>         printf("Canceling thread\\n");
>         s = pthread_cancel(thr);
>         if (s != 0)
>             handle_error_en(s, "pthread_cancel");
>     }
> 
>     s = pthread_join(thr, &res);
>     if (s != 0)
>         handle_error_en(s, "pthread_join");
> 
>     if (res == PTHREAD_CANCELED)
>         printf("Thread was canceled; cnt = %d\\n", cnt);
>     else
>         printf("Thread terminated normally; cnt = %d\\n", cnt);
>     exit(EXIT_SUCCESS);
> }

I see a major deficiency in your code. Unless I am mistaken, the global 
variable <done> and <cleanup_pop_arg> are accessed from two different 
threads. Following the POSIX memory model, you need mutex to synchronize 
the visibility.

> .fi
> .SH SEE ALSO
> .BR pthread_cancel (3),
> .BR pthread_cleanup_push_defer_np (3),
> .BR pthread_setcancelstate (3),
> .BR pthread_testcancel (3),
> .BR pthreads (7)
> 

A last comment: pthread_join(3) and pthread_cond_wait(3) are CP, so it 
would be nice to describe the cancellation semantic in their respective 
man-page.

Besides that, you need clean-up handler if you use deferred cancellation 
on pthread_cond_wait(3). Indeed, when this function is cancelled, the 
mutex is relocked.So, you need clean-up handler to unlock the mutex.
--
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

Re: For review: pthread_cleanup_push.3

[Michael Kerrisk]

Hi Loic,

On Sat, Nov 22, 2008 at 2:17 AM, Loic Domaigne <tech-Z4JMKDdsf89Wk0Htik3J/w@public.gmane.org> wrote:
> Hi Michael,
>
> the last review for today.

Thanks!

[...]

>> A cancellation clean-up handler is popped from the stack
>> and executed in the following circumstances:
>> .IP 1. 3
>> When a thread is canceled,
>> all of the stacked clean-up handlers are popped and executed in
>> the reverse of the order in which they were pushed onto the stack.
>> .IP 2.
>> When a thread terminates by calling
>> .BR pthread_exit (3),
>> all clean-up handlers are executed as described in the preceding point.
>> (Clean-up handlers are \fInot\fP called if the thread terminates by
>> performing a
>> .I return
>> from the thread start function.)
>
> Generally speaking, it is left to the implementation to call or not
> clean-up handlers when a thread returns from the start function.

Is it?  As far as I can see POSIX.1 just says the result is
"undefined".  Does that mean it's up to the implementation?  I'm not
sure.  Anyway< I added this text to NOTES:

       POSIX.1  says that the effect of using return, break, continue,
       or   goto   to   prematurely   leave    a    block    bracketed
       pthread_cleanup_push()  and pthread_cleanup_pop() is undefined.
       Portable applications should avoid doing this.

Thanks for spotting this.

> The behavior you are describing is Linux specific; so perhaps you should put
> this in the NOTE, in the same way that you mentioned that
> pthread_cleanup_{push/pop} are macro on Gnu/Linux.

See above.

[...]

>> This loop executes a global variable,
>> .IR cnt ,
>> once each second.
>
> s/executes/increments/

Fixed.

[...]

>>> From the above, we see that the thread was canceled,
>
> garbage '>' ?

Not sure what happened there.  Maybe gmail's web UI got confused.

[...]

>>> From the above, we see that the clean-up handler was not executed
>>> (because
>
> garbage '>' ?

See above

>> .I cleanup_pop_arg
>> was 0), and therefore the value of
>> .I cnt
>> was not reset.
>>
>> In the next run, the main program sets a global variable that
>> causes the other thread to terminate normally,
>> and supplies a non-zero value for
>> .IR cleanup_pop_arg :
>>
>> .in +4n
>> .nf
>> $ \fB./a.out x 1\fP
>> New thread started
>> cnt = 0
>> cnt = 1
>> Called clean-up handler
>> Thread terminated normally; cnt = 0
>> .fi
>> .in
>>
>> In the above, we see that although the thread was not canceled,
>> the clean-up handler was executed, because the argument given to
>> .BR pthread_cleanup_pop ()
>> was non-zero.
>> .SS Program source
>> \&
>> .nf
>> #include <pthread.h>
>> #include <sys/types.h>
>> #include <stdio.h>
>> #include <stdlib.h>
>> #include <unistd.h>
>> #include <errno.h>
>>
>> #define handle_error_en(en, msg) \\
>>        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
>>
>> static int done = 0;
>> static int cleanup_pop_arg = 0;
>> static int cnt = 0;
>>
>> static void
>> cleanup_handler(void *arg)
>> {
>>    printf("Called clean\-up handler\\n");
>>    cnt = 0;
>> }
>>
>> static void *
>> thread_start(void *arg)
>> {
>>    time_t start, curr;
>>
>>    printf("New thread started\\n");
>>
>>    pthread_cleanup_push(cleanup_handler, NULL);
>>
>>    curr = start = time(NULL);
>>
>>    while (!done) {
>>        pthread_testcancel();           /* A cancellation point */
>>        if (curr < time(NULL)) {
>>            curr = time(NULL);
>>            printf("cnt = %d\\n", cnt);  /* A cancellation point */
>
> printf() is not a mandatory CP (but is a CP on Linux).

Yes, but I think no change is required -- or do you think something is required.

>>            cnt++;
>>        }
>>    }
>>
>>    pthread_cleanup_pop(cleanup_pop_arg);
>>    return NULL;
>> }
>>
>> int
>> main(int argc, char *argv[])
>> {
>>    pthread_t thr;
>>    int s;
>>    void *res;
>>
>>    s = pthread_create(&thr, NULL, thread_start, (void *) 1);
>
> Why (void*) 1 as arg?

Because I failed to clean-up after extracting code from another example...

Fixed now.

>>    if (s != 0)
>>        handle_error_en(s, "pthread_create");
>>
>>    sleep(2);           /* Allow new thread to run a while */
>>
>>    if (argc > 1) {
>>        if (argc > 2)
>>            cleanup_pop_arg = atoi(argv[2]);
>>        done = 1;
>>
>>    } else {
>>        printf("Canceling thread\\n");
>>        s = pthread_cancel(thr);
>>        if (s != 0)
>>            handle_error_en(s, "pthread_cancel");
>>    }
>>
>>    s = pthread_join(thr, &res);
>>    if (s != 0)
>>        handle_error_en(s, "pthread_join");
>>
>>    if (res == PTHREAD_CANCELED)
>>        printf("Thread was canceled; cnt = %d\\n", cnt);
>>    else
>>        printf("Thread terminated normally; cnt = %d\\n", cnt);
>>    exit(EXIT_SUCCESS);
>> }
>
> I see a major deficiency in your code. Unless I am mistaken, the global
> variable <done> and <cleanup_pop_arg> are accessed from two different
> threads.

True.

> Following the POSIX memory model, you need mutex to synchronize the
> visibility.

Please educate me about the POSIX memory model ;-).  Say some more
here please.  Are you meaning that the change made in main are not
guaranteed to visible in the other thread, unless I use a
synchronization mechanism?  (or, perhaps, a barrier?)

>> .fi
>> .SH SEE ALSO
>> .BR pthread_cancel (3),
>> .BR pthread_cleanup_push_defer_np (3),
>> .BR pthread_setcancelstate (3),
>> .BR pthread_testcancel (3),
>> .BR pthreads (7)
>>
>
> A last comment: pthread_join(3) and pthread_cond_wait(3) are CP, so it would
> be nice to describe the cancellation semantic in their respective man-page.

Well, it would be nice to explain the CP semantics of every glibc
function, but that's a prpoblem still to be resolved, right?

> Besides that, you need clean-up handler if you use deferred cancellation on
> pthread_cond_wait(3). Indeed, when this function is cancelled, the mutex is
> relocked.So, you need clean-up handler to unlock the mutex.

So, I'm unclear here: what specifically are you suggesting needs to be
changed, and on what page?

Thanks for all these comments Loic!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
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

Re: For review: pthread_cleanup_push.3

[Loic Domaigne]

Gidday Michael,

let's see...

>>> A cancellation clean-up handler is popped from the stack
>>> and executed in the following circumstances:
>>> .IP 1. 3
>>> When a thread is canceled,
>>> all of the stacked clean-up handlers are popped and executed in
>>> the reverse of the order in which they were pushed onto the stack.
>>> .IP 2.
>>> When a thread terminates by calling
>>> .BR pthread_exit (3),
>>> all clean-up handlers are executed as described in the preceding point.
>>> (Clean-up handlers are \fInot\fP called if the thread terminates by
>>> performing a
>>> .I return
>>> from the thread start function.)
>> Generally speaking, it is left to the implementation to call or not
>> clean-up handlers when a thread returns from the start function.
> 
> Is it?  As far as I can see POSIX.1 just says the result is
> "undefined".  Does that mean it's up to the implementation?  I'm not
> sure.  Anyway< I added this text to NOTES:
> 
>        POSIX.1  says that the effect of using return, break, continue,
>        or   goto   to   prematurely   leave    a    block    bracketed
>        pthread_cleanup_push()  and pthread_cleanup_pop() is undefined.
>        Portable applications should avoid doing this.
> 
> Thanks for spotting this.

Tru64 implements the clean-up behavior when leaving the scope of 
pthread_cleanup_{push,pop} with a return.

Interesting c.p.t. threads on this issue:
http://groups.google.de/group/comp.programming.threads/browse_thread/thread/2a1cf7d5d44989a9/1b7431bc0e265cae
http://groups.google.de/group/comp.programming.threads/browse_thread/thread/295beb4eb09b610e/5257747c038d5162

By the way, even recognized UNIX Author errs:
http://www.apuebook.com/errata.html (Entry #13)

>>> .nf
>>> #include <pthread.h>
>>> #include <sys/types.h>
>>> #include <stdio.h>
>>> #include <stdlib.h>
>>> #include <unistd.h>
>>> #include <errno.h>
>>>
>>> #define handle_error_en(en, msg) \\
>>>        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
>>>
>>> static int done = 0;
>>> static int cleanup_pop_arg = 0;
>>> static int cnt = 0;
>>>
>>> static void
>>> cleanup_handler(void *arg)
>>> {
>>>    printf("Called clean\-up handler\\n");
>>>    cnt = 0;
>>> }
>>>
>>> static void *
>>> thread_start(void *arg)
>>> {
>>>    time_t start, curr;
>>>
>>>    printf("New thread started\\n");
>>>
>>>    pthread_cleanup_push(cleanup_handler, NULL);
>>>
>>>    curr = start = time(NULL);
>>>
>>>    while (!done) {
>>>        pthread_testcancel();           /* A cancellation point */
>>>        if (curr < time(NULL)) {
>>>            curr = time(NULL);
>>>            printf("cnt = %d\\n", cnt);  /* A cancellation point */
>> printf() is not a mandatory CP (but is a CP on Linux).
> 
> Yes, but I think no change is required -- or do you think something is required.

No. Just wanted to make you aware that your program might break on 
platform where printf() is not a CP. But I Agree: this is just 
irrelevant here ;-)

>>>            cnt++;
>>>        }
>>>    }
>>>
>>>    pthread_cleanup_pop(cleanup_pop_arg);
>>>    return NULL;
>>> }
>>>
>>> int
>>> main(int argc, char *argv[])
>>> {
>>>    pthread_t thr;
>>>    int s;
>>>    void *res;
>>>
>>>    s = pthread_create(&thr, NULL, thread_start, (void *) 1);
>> Why (void*) 1 as arg?
> 
> Because I failed to clean-up after extracting code from another example...
 >
> Fixed now.

I'd have bet...

>>>    if (s != 0)
>>>        handle_error_en(s, "pthread_create");
>>>
>>>    sleep(2);           /* Allow new thread to run a while */
>>>
>>>    if (argc > 1) {
>>>        if (argc > 2)
>>>            cleanup_pop_arg = atoi(argv[2]);
>>>        done = 1;
>>>
>>>    } else {
>>>        printf("Canceling thread\\n");
>>>        s = pthread_cancel(thr);
>>>        if (s != 0)
>>>            handle_error_en(s, "pthread_cancel");
>>>    }
>>>
>>>    s = pthread_join(thr, &res);
>>>    if (s != 0)
>>>        handle_error_en(s, "pthread_join");
>>>
>>>    if (res == PTHREAD_CANCELED)
>>>        printf("Thread was canceled; cnt = %d\\n", cnt);
>>>    else
>>>        printf("Thread terminated normally; cnt = %d\\n", cnt);
>>>    exit(EXIT_SUCCESS);
>>> }
>> I see a major deficiency in your code. Unless I am mistaken, the global
>> variable <done> and <cleanup_pop_arg> are accessed from two different
>> threads.
> 
> True.
> 
>> Following the POSIX memory model, you need mutex to synchronize the
>> visibility.
> 
> Please educate me about the POSIX memory model ;-).  Say some more
> here please.  Are you meaning that the change made in main are not
> guaranteed to visible in the other thread, unless I use a
> synchronization mechanism?  (or, perhaps, a barrier?)

Oh, that's a long story. Tomorrow perhaps (I just came home, and I guess 
Antje would like to spend some time with me...)

>>> .fi
>>> .SH SEE ALSO
>>> .BR pthread_cancel (3),
>>> .BR pthread_cleanup_push_defer_np (3),
>>> .BR pthread_setcancelstate (3),
>>> .BR pthread_testcancel (3),
>>> .BR pthreads (7)
>>>
>> A last comment: pthread_join(3) and pthread_cond_wait(3) are CP, so it would
>> be nice to describe the cancellation semantic in their respective man-page.
> 
> Well, it would be nice to explain the CP semantics of every glibc
> function, but that's a prpoblem still to be resolved, right?

Yes, you are perfectly right.

Regarding the Pthreads functions:
- for pthread_cond_wait(3), you need a cleanup handler to release the 
mutex associated to the condvar if the thread currently waiting on this 
condvar is canceled.
- for pthread_join(3), you need to describe what happens to the thread 
that was about being joined by the thread you just canceled.


>> Besides that, you need clean-up handler if you use deferred cancellation on
>> pthread_cond_wait(3). Indeed, when this function is cancelled, the mutex is
>> relocked.So, you need clean-up handler to unlock the mutex.
> 
> So, I'm unclear here: what specifically are you suggesting needs to be
> changed, and on what page?

I am suggesting to describe in the man-page of pthread_cond_wait(3) what 
does happen if a thread waiting on the condvar gets canceled.

In addition, it is perhaps a good idea to add a reference <SEE also 
pthread_cond_wait(3)> for the present man-page.

HTH,
Loïc.
--
--
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

Re: For review: pthread_cleanup_push.3

[Loic Domaigne]

Gidday Michael,

IIRC, I had an issue left:

>>> I see a major deficiency in your code. Unless I am mistaken, the global
>>> variable <done> and <cleanup_pop_arg> are accessed from two different
>>> threads.
>>
>> True.
>>
>>> Following the POSIX memory model, you need mutex to synchronize the
>>> visibility.
>>
>> Please educate me about the POSIX memory model ;-).  Say some more
>> here please.  Are you meaning that the change made in main are not
>> guaranteed to visible in the other thread, unless I use a
>> synchronization mechanism?  (or, perhaps, a barrier?)
> 
> Oh, that's a long story. Tomorrow perhaps (I just came home, and I guess 
> Antje would like to spend some time with me...)

Please refer to St Butenhof's bible "Programming with POSIX Threads", 
§3.4, pp88-95.

An excerpt can be found at:
http://markmail.org/message/24zdwjjkbe4dqz5o

Basically:

1) the values you write prior to pthread_create(3) can be seen in the 
new thread.

2) the values you write prior to mutex_unlock(3) can be seen in any 
thread that locks later the same mutex.

3) the values you write prior to terminating a thread can be seen in the 
thread that joins.

4) the values you write prior to pthread_cond_{signal,broadcast}(3) can 
be seen by any thread that is awakened.

Failing to comply these rules may cause your program to fail in very 
subtle ways on multi-processors machine. Even if I may save here and 
there a mutex; I apply those rules religiously (but, yeah, I am a 
Pthreads fanatic ;-)

HTH,
Loïc.
--
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