pthread_cancel手册翻译

原文链接：https://blog.csdn.net/qq_51470638/article/details/127641034

NAME

pthread_cancel - 向线程发送取消请求。

SYNOPSIS

#include 
int pthrread_cancel(pthread_t thread);
1
2

编译，并用-pthread链接。

DESCRIPTION

pthread_cancel()函数向thread线程发送取消请求。至于是否以及何时目标线程会对取消请求做出响应，依赖于该线程控制下的两个属性： 它的可取消状态（cancelability state）和类型（ type）。

cancelability state

• 一个线程的可取消状态（cancelability state）（这由pthread_setcancelstate(3)确定），可以启用（新线程默认开启）或禁用。
• 如果一个线程禁用了取消性（cancellation），那么一个取消请求会一直保留在队列里，直到这个线程启用取消性。
• 如果一个线程已经启用了取消性，那么它的可取消类型（cancelabilty type）决定了何时取消发生。

cancelability type

• 一个线程的可取消类型（cancelabilty type），可能是异步的（asynchronous）或延期的（deferred）（新线程默认为deferred）。
• 异步取消性意味着：线程可以在任何时刻取消（通常是立刻，但是系统不保证是这样）。
• 延期取消性意味着：取消将会推迟发生，直到下一次调用一个函数——这个函数得是一个取消点（cancellation point）。
• 哪些函数可用作为取消点？这在pthreads(7)提供了一份函数列表。

当对一个取消请求执行操作时，下面的步骤会发生（按顺序的）：

1. 取消清理程序（cancellation clean-up handlers）出栈（按照它们被入栈的相反顺序）并被调用。（参见pthread_cleanup_push(3)）
2. 线程特定的数据析构函数被调用——按照未指定的顺序。（参见pthread_key_create(3)）
3. 线程终止。（参见pthread_exit(3)）

对于pthread_cancel()上面的是异步发生的；pthread_cancel()的返回状态仅仅通知调用者：取消请求是否成功进入了取消队列。

在一个被取消的线程终结后，使用pthread_join(3)连接线程会获取PTHREAD_CANCELED作为这个线程的退出状态（连接线程是唯一可以知道取消已经完成了的途径）。

RETURN VALUE

成功返回0，失败返回非0；

ERRORS

ESRCH 找不到所给线程ID对应的线程。

ATTRIBUTES

有关本节使用的属于，参见attributes(7)

CONFORMING TO

POSIX.1-2001, POSIX.1-2008.

NOTES

在Linux上，取消是通过信号来实现的。在NPTL线程实现中，第一个实时信号（即信号 32）用于这个目的。在Linux线程中，如果实时信号可用，那么第二个实时信号被使用，否则会使用SIGUSR2。

EXAMPLES

下面的程序创建一个线程，然后取消它。主线程连接这个取消的来显来检查它的退出状态——应为PTHREAD_CANCELED。下面的shell会话显示了这个程序运行结果：

$ ./a.out
thread_func(): started; cancellation disabled
main(): sending cancellation request
thread_func(): about to enable cancellation
main(): thread was canceled
1
2
3
4
5

#include 
#include 
#include 
#include 
#include 

#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);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

SEE ALSO

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)

COLOPHON

此页面是 Linux man-pages project 5.10 的一部分。一个项目描述、关于报告错误的信息以及最新的此页面的版本，可以在https://www.kernel.org/doc/man-pages/找到。