Index for Section 3

Alphabetical listing for P

Bottom of page

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

SYNOPSIS
  #include <pthread.h>

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

LIBRARY
  DECthreads POSIX 1003.1c Library (libpthread.so)

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 controls the one-time execution code. Each
      one-time execution routine must have its own unique pthread_once_t
      record.

  routine
      Address of a procedure to be executed once. This routine is called only
      once, regardless of the number of times it and its associated
      once_control block 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 routine with no arguments. Subsequent
  calls to pthread_once(3) with the same once_control will not call the
  routine. On return from pthread_once(3), it is guaranteed that the 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 a routine that directly or indirectly results in a recursive
  call to pthread_once(3) and that specifies the same 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

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

Index for Section 3

Alphabetical listing for P

Top of page