pthread_cond_init 等函数 man 手册翻译

PTHREAD_COND(3)                                                               PTHREAD_COND(3)


NAME
       pthread_cond_init,  pthread_cond_destroy,  pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timed‐
       wait - operations on conditions


SYNOPSIS
       #include <pthread.h>

       pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

       int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *cond_attr);

       int pthread_cond_signal(pthread_cond_t *cond);

       int pthread_cond_broadcast(pthread_cond_t *cond);

       int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);

       int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);

       int pthread_cond_destroy(pthread_cond_t *cond);


DESCRIPTION
       A condition (short for "condition variable") is a synchronization device that allows threads to suspend execution and relinquish the processors until some predicate on shared data is satisfied. The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, suspending the thread  execution  until  another  thread signals the condition.
	   /*条件("条件变量"的缩写)是一种同步机制，它允许线程暂停执行并放弃处理器的时间片，直到满足对共享数据的某些断言。条件变量的基本操作是：发出条件变量信号(当断言变为真时)，并等待条件变量，暂停线程执行直到另一个线程发出条件变量信号。*/

       A condition variable must always be associated with a mutex, to avoid the race condition where a thread prepares to wait on a condition variable and another thread signals the condition just before the first thread actually waits on it.
	   /*条件变量必须始终与互斥锁一起使用，以避免一下条件竞争的发生：一个线程准备等待条件变量而另一个线程信号恰恰在第一个线程激活等待前发送条件变量的信号。*/

       pthread_cond_init initializes the condition variable cond, using the condition attributes specified in cond_attr, or default attributes if cond_attr is NULL. The LinuxThreads implementation supports no attributes for conditions, hence the cond_attr parameter is actually ignored.
	   /*pthread_cond_init 函数使用 cond_attr 中指定的条件属性初始化条件变量 cond，如果 cond_attr 为 NULL，则初始化默认属性。 LinuxThreads 实现支持无属性的条件变量，因此实际上忽略了 cond_attr 参数。*/
	   

       Variables of type pthread_cond_t can also be initialized statically, using the constant PTHREAD_COND_INITIALIZER.
	   /*也可以使用常量 PTHREAD_COND_INITIALIZER 静态初始化 pthread_cond_t 类型的变量。*/

       pthread_cond_signal restarts one of the threads that are waiting on the condition variable cond. If no threads are waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it is not specified which.
	   /*pthread_cond_signal 函数用于重新启动正在等待条件变量 cond 的其中一个线程。如果没有线程等待 cond，则没有任何事情发生。 如果多个线程正在等待 cond，则只重新启动一个，但是没有指定哪个。*/

       pthread_cond_broadcast restarts all the threads that are waiting on the condition variable cond. Nothing happens if no threads are waiting on cond.
	   /*pthread_cond_broadcast 函数用于重新启动等待条件变量 cond 的所有线程。如果没有线程等待 cond，则没有任何事情发生。*/

       pthread_cond_wait atomically unlocks the mutex (as per pthread_unlock_mutex) and waits for the condition variable cond to be signaled. The thread execution is suspended and does not consume any CPU time until the condition variable is signaled. The mutex must be locked by the calling thread on entrance to pthread_cond_wait. Before returning to the calling thread, pthread_cond_wait re-acquires mutex (as per pthread_lock_mutex).
	   /*pthread_cond_wait 函数以原子方式解锁互斥锁(根据 pthread_unlock_mutex)并等待条件变量 cond 发出信号。 线程执行被挂起，并且在发出条件变量信号之前不消耗任何 CPU 时间。 必须在进入 pthread_cond_wait 时由调用线程锁定互斥锁。 在返回调用线程之前，pthread_cond_wait 重新获取互斥锁(根据 pthread_lock_mutex)。*/

       Unlocking the mutex and suspending on the condition variable is done atomically. Thus, if all threads always acquire the mutex before signaling the condition, this guarantees that the condition cannot be signaled (and thus ignored) between the time a thread locks the mutex and the time it waits on the condition variable.
	   /*解锁互斥锁并暂停条件变量是以原子方式完成的。 因此，如果所有线程在发出条件信号之前始终获取互斥锁，则可以保证在线程锁定互斥锁的时间与它在条件变量上等待的时间之间不会发出信号（从而忽略）。*/

       pthread_cond_timedwait  atomically unlocks mutex and waits on cond, as pthread_cond_wait does, but it also bounds the duration of the wait. If cond has not been signaled within the amount of time specified by abstime, themutex is re-acquired and pthread_cond_timedwait returns the error ETIMEDOUT.  The abstime parameter specifies an absolute time, with the same origin as time(2) and gettimeofday(2): an abstime of 0 corresponds to 00:00:00 GMT, January 1, 1970.
	   /*pthread_cond_timedwait 原子地解锁互斥锁并等待 cond，就像 pthread_cond_wait 那样，但它也限制了等待的持续时间。 如果未在 abstime 指定的时间内发出 cond 信号，则重新获取互斥锁，并且 pthread_cond_timedwait 返回错误 ETIMEDOUT。 abstime 参数指定绝对时间，其原点与 time(2)和 gettimeofday(2)相同：abstime 为 0 对应于 1970年1月1日 GMT 00:00:00。*/

       pthread_cond_destroy destroys a condition variable, freeing the resources it might hold. No threads must be waiting on the condition variable on entrance to pthread_cond_destroy. In the LinuxThreads implementation, no resources are associated with condition variables, thus pthread_cond_destroy actually does nothing except checking that the condition has no waiting threads.
	   /*pthread_cond_destroy 函数用于销毁一个条件变量，释放它可能拥有的资源。 在进入 pthread_cond_destroy 时，没有线程必须等待条件变量。 在 LinuxThreads 实现中，没有资源与条件变量相关联，因此除了检查条件没有等待线程之外，pthread_cond_destroy 实际上什么都不做。*/


CANCELLATION
       pthread_cond_wait and pthread_cond_timedwait are cancellation points. If a thread is cancelled while suspended in one of these functions, the thread immediately resumes  execution, then locks again the mutex argument to pthread_cond_wait and pthread_cond_timedwait, and  finally executes the cancellation. Consequently, cleanup handlers are assured that mutex is locked when they are called.
	   /*pthread_cond_wait 函数和 pthread_cond_timedwait 函数是取消点。 如果线程在其中一个函数中挂起时被取消，则线程立即恢复执行，然后再次将 mutex 参数锁定到 pthread_cond_wait 和 pthread_cond_timedwait，最后执行取消。因此，清理处理程序可确保在调用互斥锁时将其锁定。*/


ASYNC-SIGNAL SAFETY
       The condition functions are not async-signal safe, and should not be called from a signal  handler. In particular, calling pthread_cond_signal or pthread_cond_broadcast from a signal handler may deadlock the calling thread.
	   /*条件函数不是异步信号安全的，不应该从信号处理程序调用。 特别是，从信号处理程序调用 pthread_cond_signal 或 pthread_cond_broadcast 可能会使调用线程死锁。*/


RETURN VALUE
       All condition variable functions return 0 on success and a non-zero error code on error.
	   /*所有条件变量函数在成功时返回0，在出错时返回非零错误代码。*/


ERRORS
       pthread_cond_init, pthread_cond_signal, pthread_cond_broadcast, and pthread_cond_wait never return an error code.

       The pthread_cond_timedwait function returns the following error codes on error:

		ETIMEDOUT	the condition variable was not signaled until the timeout specified by abstime

		EINTR		pthread_cond_timedwait was interrupted by a signal

       The pthread_cond_destroy function returns the following error code on error:

		EBUSY		some threads are currently waiting on cond.


AUTHOR
       Xavier Leroy <[email protected]>


SEE ALSO
       pthread_condattr_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3), gettimeofday(2), nanosleep(2).


EXAMPLE
       Consider  two shared variables x and y, protected by the mutex mut, and a condition variable cond that is to be signaled when‐
       ever x becomes greater than y.


              int x,y;
              pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
              pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

       Waiting until x is greater than y is performed as follows:


              pthread_mutex_lock(&mut);
              while (x <= y) {
                      pthread_cond_wait(&cond, &mut);
              }
              /* operate on x and y */
              pthread_mutex_unlock(&mut);

       Modifications on x and y that may cause x to become greater than y should signal the condition if needed:


              pthread_mutex_lock(&mut);
              /* modify x and y */
              if (x > y) pthread_cond_broadcast(&cond);
              pthread_mutex_unlock(&mut);

       If it can be proved that at most one waiting thread needs to be waken up (for instance, if there are only two threads communi‐
       cating  through  x and y), pthread_cond_signal can be used as a slightly more efficient alternative to pthread_cond_broadcast.
       In doubt, use pthread_cond_broadcast.

       To wait for x to becomes greater than y with a timeout of 5 seconds, do:


              struct timeval now;
              struct timespec timeout;
              int retcode;

              pthread_mutex_lock(&mut);
              gettimeofday(&now);
              timeout.tv_sec = now.tv_sec + 5;
              timeout.tv_nsec = now.tv_usec * 1000;
              retcode = 0;
              while (x <= y && retcode != ETIMEDOUT) {
                      retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
              }
              if (retcode == ETIMEDOUT) {
                      /* timeout occurred */
              } else {
                      /* operate on x and y */
              }
              pthread_mutex_unlock(&mut);
			  

 LinuxThreads                                                         PTHREAD_COND(3)