pthread_once(3T)

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 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.) 

For a multithreaded process, a simple initialization flag is not sufficient; the flag must be protected against modification by multiple threads. Consequently, this flag has to be protected by a mutex that has to be initialized only once, and so on. A multithreaded program should use initialization similar to:

static pthread_once_t  once_control = PTHREAD_ONCE_INIT; 
extern void initialize(); 
  
(void)pthread_once(&once_control, initialize); 
  
(Rest of the code after initialization.) 

AUTHOR

pthread_once() was derived from the IEEE POSIX P1003.1c standard.

STANDARDS CONFORMANCE

pthread_once(): POSIX 1003.1c.