Content-type: text/html Man page of tis_once

tis_once

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

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

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. 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 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: 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:42:25 GMT, October 02, 2010