pthread_once - Calls a routine to be executed by a single
thread, once.
#include <pthread.h>
int pthread_once(
pthread_once_t *once_control,
void (*routine)(void) );
DECthreads POSIX 1003.1c Library (libpthread.so)
Interfaces documented on this reference page conform to
industry standards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program
Interface
Address of a record that controls the one-time execution
code. Each one-time execution routine must have its own
unique pthread_once_t record. Address of a procedure to
be executed once. This routine is called only once,
regardless of the number of times it and its associated
once_control block are passed to pthread_once(3).
The first call to this routine by any thread in a process
with a given once_control will call the specified routine
with no arguments. Subsequent calls to pthread_once(3)
with the same once_control will not call the routine. On
return from pthread_once(3), it is guaranteed that the
routine has completed.
For example, a mutex or a per-thread context key must be
created exactly once. Calling pthread_once(3) ensures that
the initialization is serialized across multiple threads.
Other threads that reach the same point in the code would
be delayed until the first thread is finished.
If you specify a routine that directly or indirectly
results in a recursive call to pthread_once(3) and that
specifies the same routine argument, the recursive call
can result in a deadlock.
To initialize the once_control record, your program can
zero out the entire structure, or you can use the
PTHREAD_ONCE_INIT macro, which is defined in the pthread.h
header file, to statically initialize that structure. If
using PTHREAD_ONCE_INIT, declare the once_control record
as follows:
pthread_once_t once_control= PTHREAD_ONCE_INIT;
Note that it is often easier to simply lock a statically
initialized mutex, check a control flag, and perform necessary
initialization (in-line) rather than using
pthread_once(3). For example, code an initialization routine
that begins with the following basic logic:
init() {
static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
static int flag = FALSE;
pthread_mutex_lock(&mutex);
if(!flag)
{
flag = TRUE;
/* initialize code */
}
pthread_mutex_unlock(&mutex); }
If an error condition occurs, this routine returns an
integer indicating the type of error. Possible return values
are as follows: Successful completion. Invalid argument.
None
Manuals: Guide to DECthreads and Programmer's Guide
pthread_once(3)
[ Back ] |