tis_once(3) — Subroutines

NAME

tis_once − Calls an initialization routine that can be executed by only one thread, once.

LIBRARY

Standard C Library (libc.so, libc.a)

SYNOPSIS

#include <tis.h>

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

STANDARDS

None

PARAMETERS

once_controlAddress 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_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_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(3) with the same once_control do not call the init_routine. On return from tis_once(3), 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(3) ensures that the initialization is serialized across multiple threads.

The once_control argument 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(3) 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(3). 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);
}

RETURN VALUES

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

0Successful completion.

[EINVAL]Invalid argument.

ERRORS