VMS Help DCE_THREADS, Application Routines, pthread_once  *Conan The Librarian (sorry for the slow response - running on an old VAX)

  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_block                Address of a record that defines the
                                one-time initialization code.  Each
                                one-time initialization routine must
                                have its own unique pthread_once_t data
                                structure.

      init_routine              Address 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

  The pthread_once() 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 thread-specfic data key must be created
  exactly once. Calling pthread_once() prevents the code that creates a
  mutex or thread-specific data 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 are delayed until the first thread is finished.

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

  This routine initializes the control record if it has not been initial-
  ized and then determines if the client one-time initialization routine
  has executed once. If it has not executed, this routine calls the ini-
  tialization 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 ini-
  tialization 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. This variable must be initialized
  using the pthread_once_init macro, as follows:

      static pthread_once_t myOnceBlock = pthread_once_init;

  RETURN VALUES

  If the function fails, errno may be set to one of the following values:

    Return   Error     Description
    __________________________________________
     0                 Successful completion.

    -1      [EINVAL]   Invalid parameter.