Digital

NAME

pthread_once − Calls an initialization routine executed by one thread, a single time. 

SYNOPSIS

#include <pthread.h>
int pthread_once(

pthread_once_t ∗once_block ,
pthread_initroutine_t init_routine );

PARAMETERS

once_blockAddress of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t. 

init_routineAddress of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_block are passed to pthread_once. 

DESCRIPTION

This routine calls an initialization routine executed by one thread, a single time. This routine allows you to create your own initialization code that is guaranteed to be run only once, even if called simultaneously by multiple threads or multiple times in the same thread. 

For example, a mutex or a per-thread context key must be created exactly once. Calling pthread_once prevents the code that creates a mutex or per-thread context from being called by multiple threads. Without this routine, the execution must be serialized so that only one thread performs the initialization. Other threads that reach the same point in the code would be delayed until the first thread is finished. 

This routine initializes the control record if it has not been initialized and then determines if the client one-time initialization routine has executed once. If it has not executed, this routine calls the initialization routine specified in init_routine. If the client one-time initialization code has executed once, this routine returns. 

The pthread_once_t data structure is a record that allows client initialization operations to guarantee mutual exclusion of access to the initialization routine, and that each initialization routine is executed exactly once. 

The client code must declare a variable of type pthread_once_t to use the client initialization operations. In a language such as Ada, which allows the pthread interface bindings to define the initial value of such a structure type, the variable is declared as follows:

once_block : pthread_once_t;

In other languages, such as C, the client source code must specify the initial value of the structure fields. This cannot be done portably.  Therefore, the interface bindings for such languages must provide a portable mechanism for properly initializing the structure when the program is compiled. In the C language binding, for example, this is done by defining a macro in the cma.h include file, as follows:

#define pthread_once_init{0, 0, 0}

Client code written in C must use this macro to declare pthread_once_t variables, as follows:

static pthread_once_t myOnceBlock = pthread_once_init;

This can be displayed anywhere a static declaration is made.  Each language interface should provide an equivalent mechanism, if possible.  When using languages that lack both a type-based initialization capability and any macro capabilities, the programmer must explicitly initialize the pthread_once_t structure to the appropriate values at compile or link time. The pthread_once_t fields, and their required values, must be documented by each implementation. 

RETURN VALUES

If an error occurs, this routine returns −1. No error values have been specified. Possible return values are as follows: