HP-UX Reference (11i v2 07/12) - 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 appli-
cation. 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 previ-
ous 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 cancellation 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
Upon successful completion,
pthread_once()
returns zero. Otherwise, an error number is returned to
indicate the error (the
errno variable is not set).
ERRORS
For each of the following conditions, if the condition is detected, the pthread_once() function returns
the corresponding error number:
[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;
}
248 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update