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

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; 
	} 
  
	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.