osf1 man page for tis_once

tis_once(3)						     Library Functions Manual						       tis_once(3)

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  ini-
       tialization 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

																       tis_once(3)