Calls a routine that is executed by a single thread, once.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_once (
             pthread_once_t   *once_control,
             void   (*routine) (void));

2  –  Arguments

 once_control

    Address of a record that controls the one-time execution code.
    Each one-time execution routine must have its own unique pthread_
    once_t record.

 routine

    Address of a procedure to be executed once. This routine is
    called only once, regardless of the number of times it and its
    associated once_control block are passed to pthread_once().

3  –  Description

    The first call to this routine by any thread in a process with
    a given once_control will call the specified routine with no
    arguments. Subsequent calls to pthread_once() with the same once_
    control will not call the routine. On return from pthread_once(),
    it is guaranteed that the routine has completed.

    For example, a mutex or a per-thread context key must be
    created exactly once. Calling pthread_once() ensures that the
    initialization is serialized across multiple threads. Other
    threads that reach the same point in the code would be delayed
    until the first thread is finished.

                                   NOTE

       If you specify a routine that directly or indirectly results
       in a recursive call to pthread_once() and that specifies the
       same routine argument, the recursive call can result in a
       deadlock.

    To initialize the once_control record, your program can zero out
    the entire structure, or you can use the PTHREAD_ONCE_INIT macro,
    which is defined in the pthread.h header file, to statically
    initialize that structure. If using PTHREAD_ONCE_INIT, declare
    the once_control record as follows:

    pthread_once_t  once_control = PTHREAD_ONCE_INIT;

    Note that it is often easier to simply lock a statically
    initialized mutex, check a control flag, and perform necessary
    initialization (in-line) rather than using pthread_once(). For
    example, you can code an initialization routine that begins with
    the following basic logic:

      init()
      {
       static pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;
       static int                flag = FALSE;

       pthread_mutex_lock(&mutex);
       if(!flag)
         {
          /* initialization code goes here */
          flag = TRUE;
         }
       pthread_mutex_unlock(&mutex);
      }

4  –  Return Values

    If an error occurs, this routine returns an integer indicating
    the type of error. Possible return values are as follows:

    Return      Description

    0           Successful completion
    [EINVAL]    Invalid argument