原生线程库常用方法 - 官方文档翻译

原生线程库 - Manual

常用方法

功能	方法名
线程创建	pthread_create
线程回收	pthread_join
线程取消	pthread_cancel
线程取消点	pthread_testcancel
线程退出	pthread_exit
线程获取ID	pthread_self
线程分离	pthread_detach

1. 线程创建

int pthread_create(pthread_t *restrict thread, const pthread_attr_t *restrict attr, void *(*start_routine)(void *), void *restrict arg);

pthread_create - create a new thread.

The pthread_create() function starts a new thread in the calling process. The new thread starts execution by invoking start_routine(); arg is passed as the sole argument of start_routine().

pthread_create()函数在调用的进程中启动一个新线程。新线程通过调用start_routine()函数开始执行；arg作为start_routine()的唯一参数传递。

The new thread terminates in one of the following ways:

新线程以以下方式之一终止：

• It calls pthread_exit(3), specifying an exit status value that is available to another thread in the same process that calls pthread_join(3).

它调用pthread_exit(3)，指定一个退出状态值，该值可由调用pthread_join(3)的进程中的另一个线程检索到。

• It returns from start_routine(). This is equivalent to calling pthread_exit(3) with the value supplied in the return statement.

从start_routine()返回。这相当于调用pthread_exit(3)，并提供返回语句中的值。

• It is canceled (see pthread_cancel(3)).

被取消（参见pthread_cancel(3)）。

• Any of the threads in the process calls exit(3), or the main thread performs a return from main(). This causes the termination of all threads in the process.

进程中的任意线程调用exit(3)，或者主线程从main()函数返回。这将导致所有线程终止。

The attr argument points to a pthread_attr_t structure whose contents are used at thread creation time to determine attributes for the new thread; this structure is initialized using pthread_attr_init(3) and related functions. If attr is NULL, then the thread is created with default attributes.

attr参数指向一个pthread_attr_t结构体，其内容在线程创建时被用来确定新线程的属性；该结构体通过pthread_attr_init(3)和相关函数进行初始化。如果attr为空，则使用默认属性创建线程。

Before returning, a successful call to pthread_create() stores the ID of the new thread in the buffer pointed to by thread; this identifier is used to refer to the thread in subsequent calls to other pthreads functions.

在成功调用pthread_create()后，返回之前，它将新线程的ID存储在由thread指向的缓冲区中；该标识符用于在以后的其他pthread函数调用中引用该线程。

The new thread inherits a copy of the creating thread's signal mask (pthread_sigmask(3)). The set of pending signals for the new thread is empty (sigpending(2)). The new thread does not inherit the creating thread's alternate signal stack (sigaltstack(2)).

新线程继承创建线程的信号掩码（pthread_sigmask(3)）。新线程的待处理信号集为空（sigpending(2)）。新线程不继承创建线程的备选信号栈（sigaltstack(2)）。

The new thread inherits the calling thread's floating-point environment (fenv(3)).

新线程继承调用线程的浮动点环境（fenv(3)）。

The initial value of the new thread's CPU-time clock is 0 (see pthread_getcpuclockid(3)).

新线程的CPU时间时钟的初始值为0（参见pthread_getcpuclockid(3)）。

2. 线程连接（回收）

int pthread_join(pthread_t thread, void **retval);

pthread_join - join with a terminated thread.

The pthread_join() function waits for the thread specified by thread to terminate. If that thread has already terminated, then pthread_join() returns immediately. The thread specified by thread must be joinable.

pthread_join()函数等待由thread指定的线程终止。如果该线程已经终止，则pthread_join()立即返回。由thread指定的线程必须是可连接的。

If retval is not NULL, then pthread_join() copies the exit status of the target thread (i.e., the value that the target thread upplied to pthread_exit(3)) into the location pointed to by retval. If the target thread was canceled, then PTHREAD_CANCELED is placed in the location pointed to by retval.

如果retval不为空，则pthread_join()将目标线程的退出状态（即目标线程提供给pthread_exit(3)的值）复制到retval指向的位置。如果目标线程被取消，则在retval指向的位置放置PTHREAD_CANCELED。

If multiple threads simultaneously try to join with the same thread, the results are undefined. If the thread calling pthread_join() is canceled, then the target thread will remain joinable (i.e., it will not be detached).

如果多个线程同时尝试与同一个线程连接，则结果是未定义的。如果调用pthread_join()的线程被取消，则目标线程将保持可连接状态（即不会被分离）。

3. 线程取消

int pthread_cancel(pthread_t thread);

pthread_cancel - send a cancelation request to a thread.

The pthread_cancel() function sends a cancelation request to the thread thread. Whether and when the target thread reacts to the ancelation request depends on two attributes that are under the control of that thread: its cancelability state and type.

pthread_cancel()函数向线程thread发送取消请求。目标线程对取消请求的响应是否以及何时发生取决于该线程控制的两个属性：其取消状态和类型。

A thread's cancelability state, determined by thread_setcancelstate(3), can be enabled (the default for new threads) or disabled. If a thread has disabled cancelation, then a cancelation request remains queued until the thread enables cancelation. If a thread has enabled cancelation, then its cancelability type determines
when cancelation occurs.

线程的取消状态由pthread_setcancelstate(3)确定，可以是启用状态（对于新线程而言是默认的）或禁用状态。如果线程禁用取消请求，则取消请求将保持在队列中，直到线程启用取消请求。如果线程启用取消请求，则取消请求的生效时间取决于其取消类型。

A thread's cancelation type, determined by pthread_setcanceltype(3), may be either asynchronous or deferred (the default for new threads). Asynchronous cancelability means that the thread can be canceled at any time (usually immediately, but the system does not guarantee this). Deferred cancelability means that cancelation will be delayed until the thread next calls a function that is a cancelation point. A list of functions that are or may be cancelation points is provided in pthreads(7).

线程的取消类型由pthread_setcanceltype(3)确定，可以是异步类型或延迟类型（对于新线程而言是默认的）。异步取消类型表示线程可以随时被取消（通常是立即，但系统不能保证）。延迟取消类型表示直到线程下次调用取消点函数时才会发生取消。关于哪些函数是或可能是取消点函数的列表，请参见pthreads(7)。

When a cancelation requested is acted on, the following steps occur for thread (in this order):

当取消请求被执行时，按照以下步骤对线程执行（顺序如下）：

(1) Cancellation clean-up handlers are popped (in the reverse of the order in which they ere pushed) and called. (See pthread_cleanup_push(3).)

（1）取消清理处理程序以反向顺序弹出并调用。（请参见pthread_cleanup_push(3)）

(2) Thread-specific data destructors are called, in an unspecified order. (See pthread_key_create(3).)

（2）调用线程特定数据析构函数，顺序不明。（请参见pthread_key_create(3)）

(3) The thread is terminated. (See pthread_exit(3).)

（3）线程被终止。（请参见pthread_exit(3)）

The above steps happen asynchronously with respect to the pthread_cancel() call; the return status of pthread_cancel() merely informs the caller whether the cancelation request was successfully queued.

上述步骤与pthread_cancel()调用异步发生；pthread_cancel()的返回状态仅通知调用方取消请求是否被成功排队。

After a canceled thread has terminated, a join with that thread using pthread_join(3) obtains PTHREAD_CANCELED as the thread's exit status. (Joining with a thread is the only way to know that cancelation has completed.)

在取消的线程终止后，使用pthread_join(3)与该线程进行连接将获得PTHREAD_CANCELED作为线程的退出状态。（连接线程是唯一知道取消已完成的方法。）

4. 线程取消点

void pthread_testcancel(void);

pthread_testcancel - request delivery of any pending cancelation request.

Calling pthread_testcancel() creates a cancelation point within the calling thread, so that a thread that is otherwise executing code that contains no cancelation points will respond to a cancelation request.

调用pthread_testcancel()在调用线程中创建一个取消点，以便一个否则执行不包含取消点的代码的线程能够响应取消请求。

If cancelability is disabled (using pthread_setcancelstate(3)), or no cancelation request is pending, then a call to pthread_testcancel() has no effect.

如果取消请求已被禁用（使用pthread_setcancelstate(3)）或没有取消请求待处理，则对pthread_testcancel()的调用没有效果。

5. 线程退出

void pthread_exit(void *retval);

pthread_exit - terminate calling thread.

The pthread_exit() function terminates the calling thread and returns a value via retval that (if the thread is joinable) is available to another thread in the same process that calls pthread_join(3).

pthread_exit()函数终止调用线程，并通过retval返回一个值（如果线程是可连接的），该值可以由同一进程内调用pthread_join(3)的另一个线程获得。

Any clean-up handlers established by pthread_cleanup_push(3) that have not yet been popped, are popped (in the reverse of the order in which they were pushed) and executed. If the thread has any thread-specific data, then, after the clean-up handlers have been executed, the corresponding destructor functions are called, in an unspecified order.

通过pthread_cleanup_push(3)建立的任何清理处理程序，尚未弹出的处理程序将以相反的顺序弹出并执行。如果线程具有任何线程特定数据，则在执行完清理处理程序后，将按照未指定的顺序调用相应的析构函数。

When a thread terminates, process-shared resources (e.g., mutexes, condition variables, semaphores, and file descriptors) are not released, and functions registered using atexit(3) are not called.

当线程终止时，共享进程资源（如互斥锁、条件变量、信号量和文件描述符）不会被释放，并且不会调用使用atexit(3)注册的函数。

After the last thread in a process terminates, the process terminates as by calling exit(3) with an exit status of zero; thus, process-shared resources are released and functions registered using atexit(3) are called.

在进程中的最后一个线程终止后，进程通过使用以零为退出状态调用exit(3)来终止；因此，共享进程资源将被释放，并调用使用atexit(3)注册的函数。

6. 线程获取ID

pthread_t pthread_self(void);

pthread_self - obtain ID of the calling thread

The pthread_self() function returns the ID of the calling thread. This is the same value that is returned in *thread in the pthread_create(3) call that created this thread.

pthread_self()函数返回调用线程的ID。这个ID与创建此线程的pthread_create(3)调用中返回的*thread值相同。

7. 线程分离

int pthread_detach(pthread_t thread);

pthread_detach - detach a thread

The pthread_detach() function marks the thread identified by thread as detached. When a detached thread terminates, its resources are automatically released back to the system without the need fo another thread to join with the terminated thread.

pthread_detach()函数将由thread标识的线程标记为已分离。当分离的线程终止时，它的资源会自动释放到系统，而无需另一个线程与已终止的线程进行连接。

Attempting to detach an already detached thread results in unspecified behavior.

尝试分离一个已经被分离的线程会导致未指定的行为。