The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2003 Edition
Copyright © 2001-2003 The IEEE and The Open Group, All Rights reserved.

NAME

pthread_once - dynamic package initialization

SYNOPSIS

[THR] [Option Start] #include <pthread.h>

int pthread_once(pthread_once_t *
once_control,
       void (*
init_routine)(void));
pthread_once_t
once_control = PTHREAD_ONCE_INIT; [Option End]

DESCRIPTION

The first call to pthread_once() by any thread in a process, with a given once_control, shall call the init_routine with no arguments. Subsequent calls of pthread_once() with the same once_control shall not call the init_routine. On return from pthread_once(), init_routine shall have completed. The once_control parameter shall determine whether the associated initialization routine has been called.

The pthread_once() function is not a cancellation point. However, if init_routine is a cancellation point and is canceled, the effect on once_control shall be as if pthread_once() was never called.

The constant PTHREAD_ONCE_INIT is defined in the <pthread.h> header.

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() shall return zero; otherwise, an error number shall be returned to indicate the error.

ERRORS

The pthread_once() function may fail if:

[EINVAL]
If either once_control or init_routine is invalid.

The pthread_once() function shall not return an error code of [EINTR].


The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

Some C libraries are designed for dynamic initialization. That is, the global initialization for the library is performed when the first procedure in the library is called. In a single-threaded program, this is normally implemented using a static variable whose value is checked on entry to a routine, as follows:

static int random_is_initialized = 0;
extern int initialize_random();

int random_function() { if (random_is_initialized == 0) { initialize_random(); random_is_initialized = 1; } ... /* Operations performed after initialization. */ }

To keep the same structure in a multi-threaded program, a new primitive is needed. Otherwise, library initialization has to be accomplished by an explicit call to a library-exported initialization function prior to any use of the library.

For dynamic library initialization in a multi-threaded process, a simple initialization flag is not sufficient; the flag needs to be protected against modification by multiple threads simultaneously calling into the library. Protecting the flag requires the use of a mutex; however, mutexes have to be initialized before they are used. Ensuring that the mutex is only initialized once requires a recursive solution to this problem.

The use of pthread_once() not only supplies an implementation-guaranteed means of dynamic initialization, it provides an aid to the reliable construction of multi-threaded and realtime systems. The preceding example then becomes:

#include <pthread.h>
static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT;
extern int initialize_random();

int random_function() { (void) pthread_once(&random_is_initialized, initialize_random); ... /* Operations performed after initialization. */ }

Note that a pthread_once_t cannot be an array because some compilers do not accept the construct &<array_name>.

FUTURE DIRECTIONS

None.

SEE ALSO

The Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

CHANGE HISTORY

First released in Issue 5. Included for alignment with the POSIX Threads Extension.

Issue 6

The pthread_once() function is marked as part of the Threads option.

The [EINVAL] error is added as a may fail case for if either argument is invalid.

End of informative text.


UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]