pthread_once(3)pthread_once(3)NAMEpthread_once - Calls a routine to be executed by a single thread, once.
SYNOPSIS
#include <pthread.h>
int pthread_once(
pthread_once_t *once_control,
void (*routine)(void) );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
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 associ‐
ated once_control block are passed to pthread_once(3).
DESCRIPTION
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. Subse‐
quent 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 fin‐
ished.
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 initial‐
ization 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); }
RETURN VALUES
If an error condition occurs, this routine returns an integer indicat‐
ing the type of error. Possible return values are as follows: Success‐
ful completion. Invalid argument.
ERRORS
None
SEE ALSO
Manuals: Guide to DECthreads and Programmer's Guide
pthread_once(3)