pthread_cleanup_push

Section: C Library Functions (3)
Updated: 2025-08-20
Index JM Home Page roff page
 

名前

pthread_cleanup_push, pthread_cleanup_pop - push and pop thread cancelation clean-up handlers  

ライブラリ

POSIX スレッドライブラリ (libpthread,~-lpthread)  

書式

#include <pthread.h>

void pthread_cleanup_push(typeof(void (void *)) *routine, void *arg);
void pthread_cleanup_pop(int execute);
 

説明

These functions manipulate the calling thread's stack of thread-cancelation 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.

pthread_cleanup_push() 関数は、 routine をクリーンアップ ハンドラーのスタックの一番上にプッシュする。 routine が後で 起動される際には、 arg が関数の引数と渡される。

pthread_cleanup_pop() 関数は、クリーンアップハンドラーの スタックの一番上のルーチンを削除する。 execute が 0 以外の場合にはそのルーチンを追加で実行する。

A cancelation clean-up handler is popped from the stack and executed in the following circumstances:

•
スレッドがキャンセルされた際に、スタックに登録された全てのクリーン アップハンドラーが取り出されて、実行される。クリーンアップハンドラーの 実行は、スタックに登録されたのと逆の順序で行われる。
•
スレッドが pthread_exit(3) を呼び出して終了する際に、全てのクリーン アップハンドラーが上の項目で述べたのと同様に実行される。 (スレッドがスレッド開始関数からの return の実行により終了する場合に は、クリーンアップハンドラーは呼び出されない。)
•
スレッドが 0 以外の execute 引数で pthread_cleanup_pop() を 呼び出した際に、スタックの一番上のクリーンアップハンドラーが取り出されて 実行される。

POSIX.1 permits pthread_cleanup_push() and pthread_cleanup_pop() to be implemented as macros that expand to text containing '{' and '}', 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 established only during the execution of a specified section of code.)

longjmp(3) (siglongjmp(3)) の呼び出しは、 pthread_cleanup_push() や pthread_cleanup_pop() の呼び出しが対と なる呼び出しがない状態で行われた場合には、どのような結果になるかは不定 である。これは jump バッファーは setjmp(3) (sigsetjmp(3)) により設 定されるからである。同様に、クリーンアップハンドラー内からの longjmp(3) (siglongjmp(3)) の呼び出しも、jump バッファーがハンドラー 内で setjmp(3) (sigsetjmp(3)) で設定されていない限り、どのような 結果になるかは不定である。  

返り値

これらの関数は値を返さない。  

エラー

エラーはない。  

属性

この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース属性値
pthread_cleanup_push(), pthread_cleanup_pop() Thread safetyMT-Safe
 

バージョン

On glibc, the pthread_cleanup_push() and pthread_cleanup_pop() functions are implemented as macros that expand to text containing '{' and '}', respectively. This means that variables declared within the scope of paired calls to these functions will be visible within only that scope.

POSIX.1 には、括弧を含む pthread_cleanup_push() と pthread_cleanup_pop() のブロックをそのままにしたままで、 return, break, continue, goto を使った場合の影響は 不定であると書かれている。 移植性が必要なアプリケーションではこれを行うのは避けるべきである。  

標準規格

POSIX.1-2008.  

歴史

POSIX.1-2001. glibc 2.0.  

例

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 pthread_cleanup_push() and pthread_cleanup_pop(). This loop increments a global variable, cnt, once each second. Depending on what command-line arguments are supplied, the main thread sends the other thread a cancelation request, or sets a global variable that causes the other thread to exit its loop and terminate normally (by doing a return).

以下のシェルセッションでは、メインスレッドはもう一つのスレッドに キャンセル要求を送信する。

$ ./a.out;
New thread started
cnt = 0
cnt = 1
Canceling thread
Called clean-up handler
Thread was canceled; cnt = 0

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

次の実行例では、メインプログラムはグローバル変数を設定して、 もう一つのスレッドが正常終了するようにしている。

$ ./a.out x;
New thread started
cnt = 0
cnt = 1
Thread terminated normally; cnt = 2

上記では、 (cleanup_pop_arg が 0 なので) クリーンアップハンドラーは 実行されておらず、その結果 cnt の値はリセットされていないことが 分かる。

次の実行例では、メインプログラムはグローバル変数を設定して、 もう一つのスレッドが正常終了するようにし、さらに cleanup_pop_arg に 0 以外の値を渡している。

$ ./a.out x 1;
New thread started
cnt = 0
cnt = 1
Called clean-up handler
Thread terminated normally; cnt = 0

上記では、スレッドはキャンセルされていないが、クリーンアップハンドラーが実行されたことが分かる。これは pthread_cleanup_pop() の引数に 0 以外を渡したからである。  

プログラムのソース

#include <err.h>
#include <errno.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

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 curr;

    printf("New thread started\n");

    pthread_cleanup_push(cleanup_handler, NULL);

    curr = time(NULL);

    while (!done) {
        pthread_testcancel();           /* A cancelation point */
        if (curr < time(NULL)) {
            curr = time(NULL);
            printf("cnt = %d\n", cnt);  /* A cancelation 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)
        errc(EXIT_FAILURE, 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)
            errc(EXIT_FAILURE, s, "pthread_cancel");
    }

    s = pthread_join(thr, &res);
    if (s != 0)
        errc(EXIT_FAILURE, 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);
}
 

関連項目

pthread_cancel(3), pthread_cleanup_push_defer_np(3), pthread_setcancelstate(3), pthread_testcancel(3), pthreads(7)


 

Index

名前
ライブラリ
書式
説明
返り値
エラー
属性
バージョン
標準規格
歴史
例
プログラムのソース
関連項目

This document was created by man2html, using the manual pages.