Manpages

名 前

pthread_cancel − ス レ ッ ド に キ ャ ン セ ル 要 求 を 送 る

書 式

#include <pthread.h>

int pthread_cancel(pthread_t thread);

−pthread で コ ン パ イ ル し て リ ン ク す る 。

説 明

pthread_cancel() 関 数 は 指 定 さ れ た ス レ ッ ド thread に キ ャ ン セ ル 要 求 を 送 信 す る 。 対 象 の ス レ ッ ド が キ ャ ン セ ル 要 求 に 反 応 す る か ど う か 、 い つ 反 応 す る か は 対 象 の ス レ ッ ド の 制 御 下 に あ る 2 つ の 属 性 、 cancelability state と typeに よ り 決 ま る 。 あ る ス レ ッ ド の cancelability state は pthread_setcancelstate(3) で 設 定 さ れ 、 enabled と disabled の い ず れ と な る (enabled が 新 し い ス レ ッ ド の デ フ ォ ル ト 値 で あ る )。 ス レ ッ ド が キ ャ ン セ ル を 無 効 に し て い た 場 合 、 キ ャ ン セ ル 要 求 は そ の ス レ ッ ド が キ ャ ン セ ル を 有 効 に す る ま で キ ュ ー に 入 れ ら れ た ま ま に な る 。 ス レ ッ ド が キ ャ ン セ ル を 有 効 に し て い た 場 合 、 cancelability type に よ っ て 、 い つ キ ャ ン セ ル が 発 生 す る か が 決 ま る 。 ス レ ッ ド の キ ャ ン セ ル 種 別 (cancelability type) は pthread_setcanceltype(3) で 設 定 さ れ 、 asynchronous か deferred の い ず れ か と な る (deferred が 新 し い ス レ ッ ド の デ フ ォ ル ト 値 で あ る )。 非 同 期 キ ャ ン セ ル (asynchronous cancelability) は 、 そ の ス レ ッ ド は い つ で も キ ャ ン セ ル さ れ る こ と を 意 味 す る (通 常 は す ぐ に キ ャ ン セ ル さ れ る が 、 シ ス テ ム が そ の こ と を 保 証 し て い る わ け で は な い )。 遅 延 キ ャ ン セ ル (deferred cancelability) で は 、 そ の ス レ ッ ド が 取 り 消 し ポ イ ン ト (cancellation point) と な っ て い る 関 数 を 次 に 呼 び 出 す ま で キ ャ ン セ ル が 遅 延 さ れ る 。 取 り 消 し ポ イ ン ト に 設 定 さ れ て い た り 設 定 し た り で き る 関 数 の リ ス ト は pthreads(7) に 記 載 し て い る 。 キ ャ ン セ ル 要 求 が 実 行 さ れ る と 、 thread で は 以 下 の ス テ ッ プ が (こ の 順 序 で ) 行 わ れ る 。

さ れ (pop さ れ )、 呼 び 出 さ れ る 。 (pthread_cleanup_push(3) 参 照 )

出 し 順 序 は 規 定 さ れ て い な い 。 (pthread_key_create(3) 参 照 )

上 記 の ス テ ッ プ は pthread_cancel() の 呼 び 出 し と は 非 同 期 に 行 わ れ る 。 pthread_cancel() の 返 却 ス テ ー タ ス は 単 に キ ャ ン セ ル 要 求 が 正 常 に キ ュ ー に 入 れ ら れ た か ど う か を 呼 び 出 し 元 に 示 す だ け の も の で あ る 。 キ ャ ン セ ル さ れ た ス レ ッ ド が 終 了 さ れ た 後 に 、 pthread_join(3) で そ の ス レ ッ ド を join す る と 、 そ の ス レ ッ ド の 終 了 ス テ ー タ ス と し て PTHREAD_CANCELED が 得 ら れ る 。 (ス レ ッ ド の join は キ ャ ン セ ル が 完 了 し た か を 知 る 唯 一 の 方 法 で あ る )

返 り 値

成 功 す る と 、 pthread_cancel() は 0 を 返 す 。 エ ラ ー の 場 合 、 0 以 外 の エ ラ ー 番 号 を 返 す 。

エ ラ ー

準 拠

POSIX.1−2001.

注 意

Linux で は 、 キ ャ ン セ ル は シ グ ナ ル を 使 っ て 実 装 さ れ て い る 。 NPTL ス レ ッ ド 実 装 で は 、 最 初 の リ ア ル タ イ ム シ グ ナ ル (つ ま り 、 シ グ ナ ル 32)が こ の た め に 使 用 さ れ る 。 LinuxThreads で は 、 リ ア ル タ イ ム シ グ ナ ル が 利 用 可 能 な 場 合 は 2 番 目 の リ ア ル タ イ ム シ グ ナ ル が 使 用 さ れ 、 そ う で な い 場 合 は SIGUSR2 が 使 用 さ れ る 。

例

以 下 の プ ロ グ ラ ム は 、 ス レ ッ ド を 一 つ 作 成 し て か ら 、 そ の ス レ ッ ド を キ ャ ン セ ル す る 。 メ イ ン ス レ ッ ド は キ ャ ン セ ル さ れ た ス レ ッ ド を ジ ョ イ ン し 、 キ ャ ン セ ル さ れ た ス レ ッ ド の 終 了 ス テ ー タ ス が PTHREAD_CANCELED か ど う か を 確 認 す る 。 以 下 の シ ェ ル セ ッ シ ョ ン は こ の プ ロ グ ラ ム を 実 行 し た 際 の 実 行 例 で あ る 。

$ ./a.out
thread_func(): started; cancellation disabled
main(): sending cancellation request
thread_func(): about to enable cancellation
main(): thread was canceled プ ロ グ ラ ム の ソ ー ス

#include <pthread.h>
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>

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

static void *
thread_func(void *ignored_argument)
{
int s;

/* Disable cancellation for a while, so that we don't
immediately react to a cancellation request */

s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
if (s != 0)
handle_error_en(s, "pthread_setcancelstate");

printf("thread_func(): started; cancellation disabled\n");
sleep(5);
printf("thread_func(): about to enable cancellation\n");

s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
if (s != 0)
handle_error_en(s, "pthread_setcancelstate");

/* sleep() is a cancellation point */

sleep(1000); /* Should get canceled while we sleep */

/* Should never get here */

printf("thread_func(): not canceled!\n");
return NULL; }

int
main(void)
{
pthread_t thr;
void *res;
int s;

/* Start a thread and then send it a cancellation request */

s = pthread_create(&thr, NULL, &thread_func, NULL);
if (s != 0)
handle_error_en(s, "pthread_create");

sleep(2); /* Give thread a chance to get started */

printf("main(): sending cancellation request\n");
s = pthread_cancel(thr);
if (s != 0)
handle_error_en(s, "pthread_cancel");

/* Join with thread to see what its exit status was */

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

if (res == PTHREAD_CANCELED)
printf("main(): thread was canceled\n");
else
printf("main(): thread wasn't canceled (shouldn't happen!)\n");
exit(EXIT_SUCCESS); }

関 連 項 目

pthread_cleanup_push(3), pthread_create(3), pthread_exit(3), pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3), pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man−pages プ ロ ジ ェ ク ト の リ リ ー ス 3.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。