Index for Section 3

Alphabetical listing for P

pthread_once(3)
NAME
  pthread_once - Calls an initialization routine to be executed by a single
  thread, once.

LIBRARY
  DECthreads POSIX 1003.1c Library (libpthread.so)

SYNOPSIS
  #include <pthread.h>

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

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS
  once_control
	    Address of a record that defines the one-time initialization
	    code.  Each one-time initialization routine 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 pthread_once(3).

DESCRIPTION
  The first call to this routine by any thread in a process with a given
  once_control will call the specified init_routine with no arguments.
  Subsequent calls to pthread_once(3) with the same once_control will not
  call the init_routine.  On return from pthread_once(3), it is guaranteed
  that the initialization routine has completed.

  For example, a mutex or a per-thread context key must be created exactly
  once.	 Calling pthread_once(3) ensures that the initialization is
  serialized across multiple threads.  Other threads that reach the same
  point in the code would be delayed until the first thread is finished.

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

  To initialize the once_control record, your program can zero out the entire
  structure, or you can use the PTHREAD_ONCE_INIT macro, which is defined in
  the pthread.h header file, to statically initialize that structure.  If
  using PTHREAD_ONCE_INIT, declare the 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 pthread_once(3).  For example, code an initialization routine
  that begins with the following basic logic:

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

	  pthread_mutex_lock(&mutex);
	  if(!flag)
	    {
	     flag = TRUE;
	     /* initialize code */
	    }
	  pthread_mutex_unlock(&mutex);
	 }

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

  0	    Successful completion.

  [EINVAL]  Invalid argument.

ERRORS
  None

RELATED INFORMATION
  Manuals: Guide to DECthreads and Programmer's Guide