pthread_mutex_init 等函数 man 手册翻译

PTHREAD_MUTEX(3) 																PTHREAD_MUTEX(3)



NAME
       pthread_mutex_init,  pthread_mutex_lock,  pthread_mutex_trylock,  pthread_mutex_unlock,  pthread_mutex_destroy - operations on mutexes


SYNOPSIS
       #include <pthread.h>

       pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;

       pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;

       pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;

       int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr);

       int pthread_mutex_lock(pthread_mutex_t *mutex);

       int pthread_mutex_trylock(pthread_mutex_t *mutex);

       int pthread_mutex_unlock(pthread_mutex_t *mutex);

       int pthread_mutex_destroy(pthread_mutex_t *mutex);


DESCRIPTION
       A mutex is a MUTual EXclusion device, and is useful for protecting shared data structures from concurrent modifications, and implementing critical sections and monitors.
	   /*互斥锁是一种 MUTual EXclusionl 机制，可用于保护共享数据结构免受并发修改，以及实现关键部分和监视器。*/

       A mutex has two possible states: unlocked (not owned by any thread), and locked (owned by one thread). A mutex can never be owned by two different threads simultaneously. A thread attempting to lock a mutex that is already locked by another thread is suspended until the owning thread unlocks the mutex first.
	   /*互斥锁有两种可能的状态：解锁（不是由任何线程拥有）和锁定（由一个线程拥有）。 互斥锁永远不能同时由两个不同的线程拥有。 尝试锁定已被另一个线程锁定的互斥锁的线程将暂停，直到拥有的线程首先解锁互斥锁。*/

       pthread_mutex_init initializes the mutex object pointed to by mutex according to the mutex attributes specified in mutexattr. If mutexattr is NULL, default attributes are used instead.
	   /*pthread_mutex_init 函数根据 mutexattr 中指定的互斥锁属性来初始化 mutex 指向的互斥锁对象。 如果 mutexattr = NULL，则使用默认属性。*/

       The LinuxThreads implementation supports only one mutex attributes, the mutex kind, which is either "fast", "recursive", or "error  checking". The kind of a mutex determines whether it can be locked again by a thread that already owns it.  The default kind is "fast". See pthread_mutexattr_init(3) for more information on mutex attributes.
	   /*LinuxThreads 实现仅支持一个互斥锁属性，即互斥类型，即"fast"、"recursive"或"error  checking"。 互斥体的类型决定了它是否可以被已经拥有它的线程再次锁定。 默认类型是"fast"。 有关互斥锁属性的更多信息，请参阅 pthread_mutexattr_init(3)。*/

       Variables of type pthread_mutex_t can also be initialized statically, using the constants PTHREAD_MUTEX_INITIALIZER (for fast mutexes), PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP (for recursive mutexes), and PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP (for error checking mutexes).
	   /*pthread_mutex_t 类型的变量也可以使用常量 PTHREAD_MUTEX_INITIALIZER(对于快速互斥锁)，PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP(对于递归互斥锁)和 PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP(用于错误检查互斥锁)静态初始化。*/

       pthread_mutex_lock locks the given mutex. If the mutex is currently unlocked, it becomes  locked and owned by the calling thread, and pthread_mutex_lock returns immediately. If the mutex is already locked by another thread, pthread_mutex_lock suspends the calling thread until the mutex is unlocked.
	   /*pthread_mutex_lock 函数用于锁定给定的互斥锁。 如果互斥锁当前已解锁，则它将被调用线程锁定并拥有，并且 pthread_mutex_lock 立即返回。 如果互斥锁已被另一个线程锁定，则 pthread_mutex_lock 将挂起调用线程，直到互斥锁被解锁。*/

       If the mutex is already locked by the calling thread, the behavior of pthread_mutex_lock depends on the kind of the mutex. If the  mutex  is of the "fast" kind, the calling thread is suspended until the mutex is unlocked, thus effectively causing the calling thread to deadlock. If the mutex is of the "error checking" kind, pthread_mutex_lock returns immediately with  the error code EDEADLK.  If the mutex is of the "recursive" kind, pthread_mutex_lock succeeds and returns immediately, recording the number of times the calling thread has locked the mutex. An equal number of pthread_mutex_unlock operations must be performed before the mutex returns to the unlocked state.
	   /*如果互斥锁已被调用线程锁定，则 pthread_mutex_lock 的行为取决于互斥锁的类型。 如果互斥锁是"fast"类型，则调用线程将被挂起，直到互斥锁被解锁，从而有效地导致调用线程死锁。 如果互斥锁属于 "error checking" 类型，则 pthread_mutex_lock 会立即返回错误代码 EDEADLK。 如果互斥锁是"recursive" 类型，则 pthread_mutex_lock 成功并立即返回，记录调用线程锁定互斥锁的次数。 在互斥锁返回解锁状态之前，必须执行相同数量的 pthread_mutex_unlock 操作。*/

       pthread_mutex_trylock behaves identically to pthread_mutex_lock, except that it does not block the calling thread if the mutex is already locked by another thread (or by the calling thread in the case of a "fast" mutex). Instead, pthread_mutex_trylock returns immediately with the error code EBUSY.
	   /*pthread_mutex_trylock 函数的行为与 pthread_mutex_lock 完全相同，只是如果互斥锁已被另一个线程（或者在"fast"互斥锁的情况下由调用线程）锁定，则它不会阻塞调用线程。相反，pthread_mutex_trylock 会立即返回错误代码 EBUSY。*/

       pthread_mutex_unlock unlocks the given mutex. The mutex is assumed to be locked and owned by the calling thread on entrance to pthread_mutex_unlock. If the mutex is of the "fast" kind, pthread_mutex_unlock always returns it to the unlocked  state. If it is of the "recursive" kind, it decrements the locking count of the mutex (number of pthread_mutex_lock operations performed on it by the calling thread), and only when this count reaches zero is the mutex actually unlocked.
	   /*pthread_mutex_unlock 函数用于解锁给定的互斥锁。假定互斥锁在 pthread_mutex_unlock 入口处被调用线程锁定并拥有。 如果互斥锁属于"fast"类型，则 pthread_mutex_unlock 将返回解锁状态。 如果它是"recursive"类型，则减少互斥锁的锁定计数(由调用线程对其执行的 pthread_mutex_lock 操作的数量)，并且仅当该计数达到零时，互斥锁才真正解锁。*/

       On "error checking" and "recursive" mutexes, pthread_mutex_unlock actually checks at run-time that the mutex is locked on entrance, and that it was locked by the same thread that is now calling pthread_mutex_unlock. If these conditions are not met, an error code is returned and the mutex remains unchanged. "Fast" mutexes perform no such checks, thus  allowing a locked mutex to be unlocked by a thread other than its owner. This is nonportable behavior and must not be relied upon.
	   /*在"error checking"和"recursive"互斥锁上，pthread_mutex_unlock 实际上在运行时检查互斥锁是否在入口处被锁定，并且它被现在调用 pthread_mutex_unlock 的同一线程锁定。 如果不满足这些条件，则返回错误代码并且互斥锁保持不变。 "Fast"互斥锁不执行此类检查，因此允许锁定的互斥锁由其所有者以外的线程解锁。 这是不可移植的行为，不得依赖。*/

       pthread_mutex_destroy destroys a mutex object, freeing the resources it might hold. The mutex must be unlocked on entrance. In the LinuxThreads implementation, no resources are associated with mutex objects, thus pthread_mutex_destroy actually does nothing except checking that the mutex is unlocked.
	   /*pthread_mutex_destroy 函数用于破坏互斥对象，释放它可能拥有的资源。 必须在入口处解锁互斥锁。 在 LinuxThreads 实现中，没有资源与互斥对象关联，因此除了检查互斥锁是否已解锁外，pthread_mutex_destroy 实际上什么都不做。*/


CANCELLATION
       None of the mutex functions is a cancellation point, not even pthread_mutex_lock, in spite of the fact that it can suspend a thread for arbitrary durations. This way, the status of mutexes at cancellation points is predictable, allowing cancellation handlers to unlock precisely those mutexes that need to be unlocked before the thread stops executing. Consequently, threads using deferred cancellation should never hold a mutex for extended periods of time.
	   /*尽管它可以在任意持续时间内挂起线程，但互斥函数都不是取消点，甚至不是pthread_mutex_lock。 这样，取消点处的互斥锁的状态是可预测的，允许取消处理程序准确地解锁在线程停止执行之前需要解锁的互斥锁。 因此，使用延迟取消的线程永远不应持有互斥锁。*/


ASYNC-SIGNAL SAFETY
       The mutex functions are not async-signal safe. What this means is that they should not be called from a signal handler. In particular, calling pthread_mutex_lock or pthread_mutex_unlock from a signal handler may deadlock the calling thread.
	   /*互斥锁功能不是异步信号安全的。 这意味着它们不应该从信号处理程序中调用。 特别是，从信号处理程序调用 pthread_mutex_lock 或 pthread_mutex_unlock 可能会使调用线程死锁。*/


RETURN VALUE
       pthread_mutex_init always returns 0. The other mutex functions return 0 on success and a non-zero error code on error.
	   /*pthread_mutex_init 始终返回 0.其他互斥锁函数在成功时返回 0，在出错时返回非零错误代码。*/


ERRORS
       The pthread_mutex_lock function returns the following error code on error:

		EINVAL	the mutex has not been properly initialized.

		EDEADLK	the mutex is already locked by the calling thread ("error checking" mutexes only).

       The pthread_mutex_trylock function returns the following error codes on error:

		EBUSY	the mutex could not be acquired because it was currently locked.

		EINVAL	the mutex has not been properly initialized.

       The pthread_mutex_unlock function returns the following error code on error:

		EINVAL	the mutex has not been properly initialized.

		EPERM	the calling thread does not own the mutex ("error checking" mutexes only).

       The pthread_mutex_destroy function returns the following error code on error:

		EBUSY	the mutex is currently locked.


AUTHOR
       Xavier Leroy <[email protected]>


SEE ALSO
       pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3), pthread_cancel(3).


EXAMPLE
       A shared global variable x can be protected by a mutex as follows:


              int x;
              pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

       All accesses and modifications to x should be bracketed by calls to pthread_mutex_lock and pthread_mutex_unlock as follows:


              pthread_mutex_lock(&mut);
              /* operate on x */
              pthread_mutex_unlock(&mut);

LinuxThreads                                         				   PTHREAD_MUTEX(3)