Content-type: text/html Man page of pthread_once

pthread_once

Section: C Library Functions (3)
Index Return to Main Contents
 

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

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. 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: Successful completion. Invalid argument.  

ERRORS

None  

RELATED INFORMATION

Manuals: Guide to DECthreads and Programmer's Guide

delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:27 GMT, October 02, 2010