pthread_once(3-thr) pthread_once(3-thr)
NAME
pthreadonce - calls an initialization routine executed by one thread,
a single time
SYNOPSIS
#include <pthread.h>
int pthreadonce(
pthreadoncet *onceblock,
pthreadinitroutinet initroutine);
PARAMETERS
onceblock Address of a record that defines the one-time initiali-
zation code. Each one-time initialization routine must
have its own unique pthreadoncet data structure.
initroutine Address of a procedure that performs the initialization.
This routine is called only once, regardless of the
number of times it and its associated onceblock are
passed to pthreadonce().
DESCRIPTION
The pthreadonce() routine calls an initialization routine executed by
one thread, a single time. This routine allows you to create your own
initialization code that is guaranteed to be run only once, even if
called simultaneously by multiple threads or multiple times in the
same thread.
For example, a mutex or a thread-specific data key must be created
exactly once. Calling pthreadonce() prevents the code that creates a
mutex or thread-specific data from being called by multiple threads.
Without this routine, the execution must be serialized so that only
one thread performs the initialization. Other threads that reach the
same point in the code are delayed until the first thread is finished.
This routine initializes the control record if it has not been ini-
tialized and then determines if the client one-time initialization
routine has executed once. If it has not executed, this routine calls
the initialization routine specified in initroutine. If the client
one-time initialization code has executed once, this routine returns.
The pthreadoncet data structure is a record that allows client ini-
tialization operations to guarantee mutual exclusion of access to the
initialization routine, and that each initialization routine is exe-
cuted exactly once.
The client code must declare a variable of type pthreadoncet to use
the client initialization operations. This variable must be initial-
ized using the pthreadonceinit macro, as follows:
static pthreadoncet myOnceBlock = pthreadonceinit;
Page 1 Reliant UNIX 5.44 Printed 11/98
pthread_once(3-thr) pthread_once(3-thr)
RETURN VALUES
If the function fails, errno may be set to one of the following
values:
EINVAL The value specified by a parameter is invalid.
Page 2 Reliant UNIX 5.44 Printed 11/98