Index for Section 3

Alphabetical listing for T

Bottom of page

tis_once(3)
NAME
  tis_once - Calls an initialization routine that can be executed by only one
  thread, once

SYNOPSIS
  #include <tis.h>

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

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

STANDARDS
  None

PARAMETERS
  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(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 option, 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		    option = FALSE;

	  tis_mutex_lock(&mutex);
	  if(!option)
	    {
	     option = 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:

  0   Successful completion.

  [EINVAL]
      Invalid argument.

ERRORS
  None

SEE ALSO
  Manuals: Guide to DECthreads and Programmer's Guide

Index for Section 3

Alphabetical listing for T

Top of page