pthread_mutexattr_initのヘルプ・マニュアル
日本語 英語
pthread_mutexattr_init --help
man pthread_mutexattr_init
PTHREAD_MUTEXATTR(3) PTHREAD_MUTEXATTR(3)
名前
pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutex-
attr_settype, pthread_mutexattr_gettype - mutex 作成時の属性
書式
#include
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int kind);
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int
*kind);
説明
mutex の属性は mutex 作成時に、 pthread_mutex_init(3) の第 2 引数として
mutex 属性オブジェクトを渡すことで指定することができる。 NULL を渡す こ
とは、すべての属性がデフォルト値に設定された mutex 属性オブジェクトを渡
すことと同等である。
pthread_mutexattr_init は mutex 属性オブジェクト attr を初期化し、す べ
ての属性をデフォルトの値に設定する。
pthread_mutexattr_destroy は mutex 属性オブジェクトを破壊する。破壊され
た mutex 属性オブジェクトは再び初期化されるまで再使用してはならな い 。
pthread_mutexattr_destroy は LinuxThreads の実装では何もしない。
LinuxThreads はただ 1 つの mutex 属性に対応している。それは mutex 種別
(mutex kind) で、「速い (fast) 」 mutex を表す PTHREAD_MUTEX_FAST_NP か
、 「再帰的な (recursive) 」 mutex を表す PTHREAD_MUTEX_RECURSIVE_NP 、
「 エ ラ ー 検 査 を 行 な う (error checking) 」 mutex を 表 す
PTHREAD_MUTEX_ERRORCHECK_NP のいずれかの値をとる。 NP という接尾辞が示
すように、これは POSIX 標準に対するポータブルでない拡張で、ポータブルな
プログラムでは用いるべきでない。
mutex 種別は、あるスレッドが自分自身で pthread_mutex_lock(3) ですでに保
持している mutex をロックしようとしたときに、何が起こるかを決定す る 。
mutex が「速い (fast) 」という種別の場合、 pthread_mutex_lock(3) は単に
呼び出しスレッドを永遠に停止させる。 mutex が「エラー 検 査 を 行 な う
(error checking) 」という種別の場合、 pthread_mutex_lock(3) はエラーコ
ード EDEADLK とともに直ちに返る。 mutex が「再帰的な (recursive) 」とい
う種別の場合、 pthread_mutex_lock(3) の呼び出しは成功の返り値とともに直
ちに返る。 mutex を保持しているスレッドが何回ロックしたかがそ の mutex
に 記録される。保持しているスレッドがロック解除状態に戻るためには、同じ
回数だけ pthread_mutex_unlock(3) を呼び出さなければならない。
デフ ォ ル ト の mutex 種 別 は 「 速 い (fast) 」 、 す な わ ち
PTHREAD_MUTEX_FAST_NP である。
pthread_mutexattr_settype は attr の mutex 種別を表す属性を kind で示さ
れる値に設定する。
pthread_mutexattr_gettype は attr の mutex 種別を表す属性を 取 得 し 、
kind で指し示される領域に格納する。
返り値
pthread_mutexattr_init お よ び pthread_mutexattr_destroy 、
pthread_mutexattr_gettype は常に 0 を返す。
pthread_mutexattr_settype は成功すると 0 を、エラーの場合非 0 のエラ ー
コードを返す。
エラー
エ ラ ーのとき、 pthread_mutexattr_settype は次のようなエラーコードを返
す:
EINVAL kind が PTHREAD_MUTEX_FAST_NP および PTHREAD_MUTEX_RECURSIVE_NP
、 PTHREAD_MUTEX_ERRORCHECK_NP のいずれでもない。
著者
Xavier Leroy
関連項目
pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3).
[訳注1] glibc-linuxthreads の最新のドキュメントは Texinfo 形式で提供 さ
れ ている。上の記述は glibc-linuxthreads-2.2 以降では正しくない。以下は
glibc-linuxthreads-2.3.1 の Texinfo ファイルからの引用で あ る 。 種 別
(kind) が型 (type) に変更されている。
LinuxThreads は ただ 1 つの mutex 属性に対応している。それは mutex 型
(mutex type) で、「速い (fast) 」 mutex を 表 す PTHREAD_MUTEX_ADAP-
TIVE_NP か、「再帰的な (recursive) 」 mutex を表す PTHREAD_MUTEX_RECUR-
SIVE_NP 、「時刻情報つき (timed) 」 mutex を表す PTHREAD_MUTEX_TIMED_NP
、 「 エ ラ ー 検 査 を 行 な う (error checking) 」 mutex を表す
PTHREAD_MUTEX_ERRORCHECK_NP のいずれかの値をとる。 NP という接尾辞が 示
すように、これは POSIX 標準に対するポータブルでない拡張で、ポータブルな
プログラムでは用いるべきでない。
mutex 型は、あるスレッドが自分自身で pthread_mutex_lock(3) ですでに保持
し て い る mutex をロックしようとしたときに、何が起こるかを決定する。
mutex が「速い (fast) 」という型の場合、 pthread_mutex_lock(3) は単に呼
び 出しスレッドを永遠に停止させる。 mutex が「エラー検査を行なう (error
checking) 」という型の場合、 pthread_mutex_lock(3) は エ ラ ー コ ー ド
EDEADLK とともに直ちに返る。 mutex が「再帰的な (recursive) 」という型
の場合、 pthread_mutex_lock(3) の呼び出しは成功の返り値とともに直ちに返
る 。 mutex を保持しているスレッドが何回ロックしたかがその mutex に記録
される。保持しているスレッドがロック解除状態に戻るためには、同じ回数 だ
け pthread_mutex_unlock(3) を呼び出さなければならない。
デ フ ォ ル ト の mutex 型 は 「 時 刻 情報つき (timed) 」、すなわち
PTHREAD_MUTEX_TIMED_NP である。
[訳注2] LinuxThreads では mutex をプロセス間で共有することはできない 。
glibc-linuxthreads-2.2 以降、次の 2 つの関数が追加されている。
int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int
*pshared);
pshared で指し示される領域に PTHREAD_PROCESS_PRIVATE を格納し、常 に 0
を返す。
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int
pshared);
pshared が PTHREAD_PROCESS_PRIVATE および PTHREAD_PROCESS_SHARED のいず
れでもない場合、 EINVAL を返す。 pshared が PTHREAD_PROCESS_SHARED の場
合、 ENOSYS を返す。それ以外の場合、 0 を返す。
LinuxThreads PTHREAD_MUTEXATTR(3)
PTHREAD_MUTEXATTR_DESTROY(3POSIX Programmer’s ManPTHREAD_MUTEXATTR_DESTROY(3P)
PROLOG
This manual page is part of the POSIX Programmer’s Manual. The Linux
implementation of this interface may differ (consult the corresponding
Linux manual page for details of Linux behavior), or the interface may
not be implemented on Linux.
NAME
pthread_mutexattr_destroy, pthread_mutexattr_init - destroy and ini-
tialize the mutex attributes object
SYNOPSIS
#include
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
DESCRIPTION
The pthread_mutexattr_destroy() function shall destroy a mutex
attributes object; the object becomes, in effect, uninitialized. An
implementation may cause pthread_mutexattr_destroy() to set the object
referenced by attr to an invalid value. A destroyed attr attributes
object can be reinitialized using pthread_mutexattr_init(); the results
of otherwise referencing the object after it has been destroyed are
undefined.
The pthread_mutexattr_init() function shall initialize a mutex
attributes object attr with the default value for all of the attributes
defined by the implementation.
Results are undefined if pthread_mutexattr_init() is called specifying
an already initialized attr attributes object.
After a mutex attributes object has been used to initialize one or more
mutexes, any function affecting the attributes object (including
destruction) shall not affect any previously initialized mutexes.
RETURN VALUE
Upon successful completion, pthread_mutexattr_destroy() and
pthread_mutexattr_init() shall return zero; otherwise, an error number
shall be returned to indicate the error.
ERRORS
The pthread_mutexattr_destroy() function may fail if:
EINVAL The value specified by attr is invalid.
The pthread_mutexattr_init() function shall fail if:
ENOMEM Insufficient memory exists to initialize the mutex attributes
object.
These functions shall not return an error code of [EINTR].
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
None.
RATIONALE
See pthread_attr_init() for a general explanation of attributes.
Attributes objects allow implementations to experiment with useful
extensions and permit extension of this volume of IEEE Std 1003.1-2001
without changing the existing functions. Thus, they provide for future
extensibility of this volume of IEEE Std 1003.1-2001 and reduce the
temptation to standardize prematurely on semantics that are not yet
widely implemented or understood.
Examples of possible additional mutex attributes that have been dis-
cussed are spin_only, limited_spin, no_spin, recursive, and metered.
(To explain what the latter attributes might mean: recursive mutexes
would allow for multiple re-locking by the current owner; metered
mutexes would transparently keep records of queue length, wait time,
and so on.) Since there is not yet wide agreement on the usefulness of
these resulting from shared implementation and usage experience, they
are not yet specified in this volume of IEEE Std 1003.1-2001. Mutex
attributes objects, however, make it possible to test out these con-
cepts for possible standardization at a later time.
Mutex Attributes and Performance
Care has been taken to ensure that the default values of the mutex
attributes have been defined such that mutexes initialized with the
defaults have simple enough semantics so that the locking and unlocking
can be done with the equivalent of a test-and-set instruction (plus
possibly a few other basic instructions).
There is at least one implementation method that can be used to reduce
the cost of testing at lock-time if a mutex has non-default attributes.
One such method that an implementation can employ (and this can be made
fully transparent to fully conforming POSIX applications) is to
secretly pre-lock any mutexes that are initialized to non-default
attributes. Any later attempt to lock such a mutex causes the implemen-
tation to branch to the "slow path" as if the mutex were unavailable;
then, on the slow path, the implementation can do the "real work" to
lock a non-default mutex. The underlying unlock operation is more com-
plicated since the implementation never really wants to release the
pre-lock on this kind of mutex. This illustrates that, depending on the
hardware, there may be certain optimizations that can be used so that
whatever mutex attributes are considered "most frequently used" can be
processed most efficiently.
Process Shared Memory and Synchronization
The existence of memory mapping functions in this volume of
IEEE Std 1003.1-2001 leads to the possibility that an application may
allocate the synchronization objects from this section in memory that
is accessed by multiple processes (and therefore, by threads of multi-
ple processes).
In order to permit such usage, while at the same time keeping the usual
case (that is, usage within a single process) efficient, a process-
shared option has been defined.
If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option,
then the process-shared attribute can be used to indicate that mutexes
or condition variables may be accessed by threads of multiple pro-
cesses.
The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the
process-shared attribute so that the most efficient forms of these syn-
chronization objects are created by default.
Synchronization variables that are initialized with the PTHREAD_PRO-
CESS_PRIVATE process-shared attribute may only be operated on by
threads in the process that initialized them. Synchronization variables
that are initialized with the PTHREAD_PROCESS_SHARED process-shared
attribute may be operated on by any thread in any process that has
access to it. In particular, these processes may exist beyond the
lifetime of the initializing process. For example, the following code
implements a simple counting semaphore in a mapped file that may be
used by many processes.
/* sem.h */
struct semaphore {
pthread_mutex_t lock;
pthread_cond_t nonzero;
unsigned count;
};
typedef struct semaphore semaphore_t;
semaphore_t *semaphore_create(char *semaphore_name);
semaphore_t *semaphore_open(char *semaphore_name);
void semaphore_post(semaphore_t *semap);
void semaphore_wait(semaphore_t *semap);
void semaphore_close(semaphore_t *semap);
/* sem.c */
#include
#include
#include
#include
#include
#include "sem.h"
semaphore_t *
semaphore_create(char *semaphore_name)
{
int fd;
semaphore_t *semap;
pthread_mutexattr_t psharedm;
pthread_condattr_t psharedc;
fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666);
if (fd < 0)
return (NULL);
(void) ftruncate(fd, sizeof(semaphore_t));
(void) pthread_mutexattr_init(&psharedm);
(void) pthread_mutexattr_setpshared(&psharedm,
PTHREAD_PROCESS_SHARED);
(void) pthread_condattr_init(&psharedc);
(void) pthread_condattr_setpshared(&psharedc,
PTHREAD_PROCESS_SHARED);
semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
PROT_READ | PROT_WRITE, MAP_SHARED,
fd, 0);
close (fd);
(void) pthread_mutex_init(&semap->lock, &psharedm);
(void) pthread_cond_init(&semap->nonzero, &psharedc);
semap->count = 0;
return (semap);
}
semaphore_t *
semaphore_open(char *semaphore_name)
{
int fd;
semaphore_t *semap;
fd = open(semaphore_name, O_RDWR, 0666);
if (fd < 0)
return (NULL);
semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
PROT_READ | PROT_WRITE, MAP_SHARED,
fd, 0);
close (fd);
return (semap);
}
void
semaphore_post(semaphore_t *semap)
{
pthread_mutex_lock(&semap->lock);
if (semap->count == 0)
pthread_cond_signal(&semapx->nonzero);
semap->count++;
pthread_mutex_unlock(&semap->lock);
}
void
semaphore_wait(semaphore_t *semap)
{
pthread_mutex_lock(&semap->lock);
while (semap->count == 0)
pthread_cond_wait(&semap->nonzero, &semap->lock);
semap->count--;
pthread_mutex_unlock(&semap->lock);
}
void
semaphore_close(semaphore_t *semap)
{
munmap((void *) semap, sizeof(semaphore_t));
}
The following code is for three separate processes that create, post,
and wait on a semaphore in the file /tmp/semaphore. Once the file is
created, the post and wait programs increment and decrement the count-
ing semaphore (waiting and waking as required) even though they did not
initialize the semaphore.
/* create.c */
#include "pthread.h"
#include "sem.h"
int
main()
{
semaphore_t *semap;
semap = semaphore_create("/tmp/semaphore");
if (semap == NULL)
exit(1);
semaphore_close(semap);
return (0);
}
/* post */
#include "pthread.h"
#include "sem.h"
int
main()
{
semaphore_t *semap;
semap = semaphore_open("/tmp/semaphore");
if (semap == NULL)
exit(1);
semaphore_post(semap);
semaphore_close(semap);
return (0);
}
/* wait */
#include "pthread.h"
#include "sem.h"
int
main()
{
semaphore_t *semap;
semap = semaphore_open("/tmp/semaphore");
if (semap == NULL)
exit(1);
semaphore_wait(semap);
semaphore_close(semap);
return (0);
}
FUTURE DIRECTIONS
None.
SEE ALSO
pthread_cond_destroy(), pthread_create(), pthread_mutex_destroy(),
pthread_mutexattr_destroy, the Base Definitions volume of
IEEE Std 1003.1-2001,
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 PTHREAD_MUTEXATTR_DESTROY(3P)