pthread_once.3t (2010 09)

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 applica-
tion. 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
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
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.)
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1