pthread_once(3) Library Functions Manual pthread_once(3)
NAME
pthread_once - Calls a routine to be executed by a single thread, once.
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
SYNOPSIS
#include <pthread.h>
int pthread_once(
pthread_once_t *once_control,
void (*routine)(void));
STANDARDS
Interfaces documented on this reference page conform to industry standards 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 asso-
ciated 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.
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 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 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);
}
RETURN VALUES
If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Suc-
cessful completion. Invalid argument.
ERRORS
None
RELATED INFORMATION
Manuals: Guide to DECthreads and Programmer's Guide
delim off
pthread_once(3)
