.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@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
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2012-06-04, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH PTHREAD_CLEANUP_PUSH 3 2020\-06\-09 Linux "Linux Programmer's Manual"
.SH 名前
pthread_cleanup_push, pthread_cleanup_pop \- スレッドの
キャンセルクリーンアップハンドラーの push/pop を行う
.SH 書式
.nf
\fB#include <pthread.h>\fP
.PP
\fBvoid pthread_cleanup_push(void (*\fP\fIroutine\fP\fB)(void *),\fP
\fB                          void *\fP\fIarg\fP\fB);\fP
\fBvoid pthread_cleanup_pop(int \fP\fIexecute\fP\fB);\fP
.PP
\fI\-pthread\fP でコンパイルしてリンクする。
.fi
.SH 説明
これらの関数は、呼び出したスレッドのスレッドキャンセル時のクリーンアッ
プハンドラーのスタックの操作を行う。クリーンアップハンドラーは、スレッドが
キャンセルされた場合 (や以下で説明する他の種々の状況において) 自動的に
実行される関数である。例えば、mutex のロック解除を行い、プロセス内の
他のスレッドが利用できるようにする関数などが考えられる。
.PP
\fBpthread_cleanup_push\fP() 関数は、 \fIroutine\fP をクリーンアップ
ハンドラーのスタックの一番上にプッシュする。 \fIroutine\fP が後で
起動される際には、 \fIarg\fP が関数の引数と渡される。
.PP
\fBpthread_cleanup_pop\fP() 関数は、クリーンアップハンドラーの
スタックの一番上のルーチンを削除する。
\fIexecute\fP が 0 以外の場合にはそのルーチンを追加で実行する。
.PP
キャンセルクリーンアップハンドラーは、以下に示す場合に
スタックから取り出され実行される。
.IP 1. 3
スレッドがキャンセルされた際に、スタックに登録された全てのクリーン
アップハンドラーが取り出されて、実行される。クリーンアップハンドラーの
実行は、スタックに登録されたのと逆の順序で行われる。
.IP 2.
スレッドが \fBpthread_exit\fP(3) を呼び出して終了する際に、全てのクリーン
アップハンドラーが上の項目で述べたのと同様に実行される。
(スレッドがスレッド開始関数からの \fIreturn\fP の実行により終了する場合に
は、クリーンアップハンドラーは\fI呼び出されない\fP。)
.IP 3.
スレッドが 0 以外の \fIexecute\fP 引数で \fBpthread_cleanup_pop\fP() を
呼び出した際に、スタックの一番上のクリーンアップハンドラーが取り出されて
実行される。
.PP
POSIX.1 では、 \fBpthread_cleanup_push\fP() と \fBpthread_cleanup_pop\fP() を
それぞれ \(aq\fB{\fP\(aq と \(aq\fB}\fP\(aq を含むテキストに展開するマクロと
して実装することを許容している。
このため、呼び出し側では、これらの関数の呼び出しが同じ関数の中で対と
なり、かつ文法的に同じネストレベル (nesting level) になることを保証
しなければならない。 (言い換えると、クリーンアップハンドラーは、コード
の特定のセクションの実行の中でのみ設定するものであると言える。)
.PP
\fBlongjmp\fP(3) (\fBsiglongjmp\fP(3)) の呼び出しは、
\fBpthread_cleanup_push\fP() や \fBpthread_cleanup_pop\fP() の呼び出しが対と
なる呼び出しがない状態で行われた場合には、どのような結果になるかは不定
である。これは jump バッファーは \fBsetjmp\fP(3) (\fBsigsetjmp\fP(3)) により設
定されるからである。同様に、クリーンアップハンドラー内からの
\fBlongjmp\fP(3) (\fBsiglongjmp\fP(3)) の呼び出しも、jump バッファーがハンドラー
内で \fBsetjmp\fP(3) (\fBsigsetjmp\fP(3)) で設定されていない限り、どのような
結果になるかは不定である。
.SH 返り値
これらの関数は値を返さない。
.SH エラー
.\" SH VERSIONS
.\" Available since glibc 2.0
エラーはない。
.SH 属性
この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
.TS
allbox;
lbw23 lb lb
l l l.
インターフェース	属性	値
T{
\fBpthread_cleanup_push\fP(),
\fBpthread_cleanup_pop\fP()
T}	Thread safety	MT\-Safe
.TE
.sp 1
.SH 準拠
POSIX.1\-2001, POSIX.1\-2008.
.SH 注意
Linux では、関数 \fBpthread_cleanup_push\fP() と \fBpthread_cleanup_pop\fP()
は、それぞれ \(aq\fB{\fP\(aq と \(aq\fB}\fP\(aq を含むテキストに展開する
マクロとして実装されている。このことは、これらの関数を対で呼び出した
スコープ内で宣言された変数は、そのスコープの中でしか参照できない
ということを意味している。
.PP
.\" The text was actually added in the 2004 TC2
POSIX.1 には、括弧を含む \fBpthread_cleanup_push\fP() と
\fBpthread_cleanup_pop\fP() のブロックをそのままにしたままで、
\fIreturn\fP, \fIbreak\fP, \fIcontinue\fP, \fIgoto\fP を使った場合の影響は
不定であると書かれている。
移植性が必要なアプリケーションではこれを行うのは避けるべきである。
.SH 例
以下のプログラムは、このページで説明した関数の簡単な使用例を示すもので
ある。このプログラムは \fBpthread_cleanup_push\fP() と
\fBpthread_cleanup_pop\fP() で囲まれたループを実行するスレッドを作成する。
このループではグローバル変数 \fIcnt\fP を 1 秒に 1 ずつ増やしていく。
指定されたコマンドライン引数の内容に基づいて、メインスレッドはもう一
つのスレッドにキャンセル要求を送ったり、もう一つのスレッドがループを
抜けて (\fIreturn\fP を呼び出して) 正常終了するようにグローバル変数を
設定したりする。
.PP
以下のシェルセッションでは、メインスレッドはもう一つのスレッドに
キャンセル要求を送信する。
.PP
.in +4n
.EX
$ \fB./a.out\fP
New thread started
cnt = 0
cnt = 1
Canceling thread
Called clean\-up handler
Thread was canceled; cnt = 0
.EE
.in
.PP
上記の実行例から、スレッドがキャンセルされ、
キャンセルクリーンアップハンドラーが呼び出され、
グローバル変数 \fIcnt\fP の値が 0 にリセットされていることが確認できる。
.PP
次の実行例では、メインプログラムはグローバル変数を設定して、
もう一つのスレッドが正常終了するようにしている。
.PP
.in +4n
.EX
$ \fB./a.out x\fP
New thread started
cnt = 0
cnt = 1
Thread terminated normally; cnt = 2
.EE
.in
.PP
上記では、 (\fIcleanup_pop_arg\fP が 0 なので) クリーンアップハンドラーは
実行されておらず、その結果 \fIcnt\fP の値はリセットされていないことが
分かる。
.PP
次の実行例では、メインプログラムはグローバル変数を設定して、
もう一つのスレッドが正常終了するようにし、さらに
\fIcleanup_pop_arg\fP に 0 以外の値を渡している。
.PP
.in +4n
.EX
$ \fB./a.out x 1\fP
New thread started
cnt = 0
cnt = 1
Called clean\-up handler
Thread terminated normally; cnt = 0
.EE
.in
.PP
上記では、スレッドはキャンセルされていないが、クリーンアップハンドラーが実行されたことが分かる。これは \fBpthread_cleanup_pop\fP()
の引数に 0 以外を渡したからである。
.SS プログラムのソース
\&
.EX
#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) \e
        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\en");
    cnt = 0;
}

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

    printf("New thread started\en");

    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\en", 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, NULL);
    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\en");
        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\en", cnt);
    else
        printf("Thread terminated normally; cnt = %d\en", cnt);
    exit(EXIT_SUCCESS);
}
.EE
.SH 関連項目
\fBpthread_cancel\fP(3), \fBpthread_cleanup_push_defer_np\fP(3),
\fBpthread_setcancelstate\fP(3), \fBpthread_testcancel\fP(3), \fBpthreads\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。