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. 

If you specify an init_routine that directly or indirectly results in a recursive call to pthread_once specifying the same init_block argument, the recursive call will result in a deadlock. 

The once_block must be declared static (for example, either extern or static in the C language), and it must be initialized at compile time. In the C language, using pthread.h or pthread_exc.h, initialize an once_block using the pthread_once_init macro. In other languages, you must initialize a pthread_once_t block to a value of three integer zeroes.  In C, that corresponds to the following:

static pthread_once_t block = {0,0,0};

RETURN VALUES

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