VMS Help POSIX Threads, TIS routines, tis_once  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Calls a one-time initialization routine that can be executed by
    only one thread, once.

1 - C Binding

    #include <tis.h>

    int
    tis_once (
          pthread_once_t   *once_control,
          void   (*init_routine) (void));

2 - Arguments

 once_control

    Address of a record (control block) that defines the one-time
    initialization code. Any one-time initialization routine in
    static storage specified by once_control must have its own unique
    pthread_once_t record.

 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_control are passed to tis_once().

3 - Description

    The first call to this routine by a process with a given once_
    control calls the init_routine with no arguments. Thereafter,
    subsequent calls to tis_once() with the same once_control do
    not call the init_routine. On return from tis_once(), it is
    guaranteed that the initialization routine has completed.

    For example, a mutex or a thread-specific data key must be
    created exactly once. In a threaded environment, calling tis_
    once() ensures that the initialization is serialized across
    multiple threads.

                                   NOTE

       If you specify an init_routine that directly or indirectly
       results in a recursive call to tis_once() and that specifies
       the same init_block argument, the recursive call results in
       a deadlock.

    The PTHREAD_ONCE_INIT macro, defined in the pthread.h header
    file, must be used to initialize a once_control record. Thus,
    your program must declare a 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 tis_once(). For
    example, you can code an "init" routine that begins with the
    following basic logic:

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

       tis_mutex_lock(&mutex);
       if(!flag)
         {
          flag = TRUE;
          /* initialize code */
         }
       tis_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.