tis_once

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

Syntax

tis_once( once_control, init_routine );

Argument Data Type Access

once_control opaque pthread_once_t modify init_routine procedure read

C Binding

#include 


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

Arguments

once_control: Address of a record (control block) that defines the one-time initialization code. Each one-time initialization routine in static storage 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.

Description

The first call to this routine by a process with a given once_control will call the init_routine with no arguments. Then subsequent calls to tis_once with the same once_control will 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 context key must be created exactly once. In a threaded environment, calling tis_once ensures that the initialization is serialized across multiple threads.

The once_control variable must be statically initialized using the PTHREAD_ONCE_INIT macro or by zeroing out the entire structure.

Note: If you specify an init_ routine that directly or indirectly results in a recursive call to tis_once specifying the same init_block argument, the recursive call will result in a deadlock.

The PTHREAD_ONCE_INIT macro is defined in the header file. A once_control record must be declared 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, code an init routine beginning 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);
  }

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.