HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

p
pthread_once(3T) pthread_once(3T)
(Pthread Library)
NAME
pthread_once() - call an initialization routine only once
SYNOPSIS
#include <pthread.h>
pthread_once_t once_control = PTHREAD_ONCE_INIT;
int pthread_once(
pthread_once_t *
once_control,
void (*
init_routine)(void)
);
Parameters
once_control Pointer to the once-control object associated with the one-time initialization function
init_routine().
init_routine The one-time initialization routine. This routine is called only once, regardless of the
number of times it and its associated once_control are passed to
pthread_once()
.
DESCRIPTION
The
pthread_once() function guarantees that init_routine
() is only called one time in an application.
This function will use the once_control object to determine if init_routine
() has previously been called via
pthread_once().
The first time
pthread_once()
is called with once_control and init_routine() causes init_routine() to
be called with no arguments. Subsequent calls to
pthread_once()
with the same once_control will not
cause init_routine
() to be called again. When pthread_once()
returns, the caller is guaranteed that
init_routine
() has been called (either just now or via a previous call).
The macro PTHREAD_ONCE_INIT
is used to statically initialize a once control block. This initialization
must be done before calling
pthread_once()
.
pthread_once() is not a cancellation point. However, the caller supplied init_routine
() may be a can-
cellation point. If the thread executing init_routine
() is canceled, the once_control argument will be set to
a state which indicates that init_routine() has not been called yet (see pthread_cancel(3T)). The next time
the
pthread_once() function is called with once_control, the init_routine
() function will be called.
The behavior of
pthread_once()
is undefined if once_control has automatic storage duration or is not
initialized by
PTHREAD_ONCE_INIT
.
RETURN VALUE
pthread_once() returns returns the following values:
0 Successful completion.
<>0 Failure. An error number is returned to indicate the error. (The
errno variable is not set.)
ERRORS
The following error value is returned by
pthread_once()
if the corresponding condition is detected.
[EINVAL] Either once_control or init_routine is invalid.
EXAMPLES
Some modules are designed for dynamic initialization, i.e., global initialization is performed when the first
function of the module is invoked. In a single-threaded program, this is generally implemented as follows:
static int initialized = FALSE;
extern void initialize();
if (!initialized) {
initialize();
initialized = TRUE;
}
(Rest of the code after initialization.)
226 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007