tis_once(3) [osf1 man page]

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)

PTHREAD_ONCE(P) 					     POSIX Programmer's Manual						   PTHREAD_ONCE(P)

NAME

       pthread_once - dynamic package initialization

SYNOPSIS

       #include <pthread.h>

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

DESCRIPTION

       The first call to pthread_once() by any thread in a process, with a given once_control, shall call the init_routine with no arguments. Sub-
       sequent calls of pthread_once() with the same once_control shall not call the init_routine. On  return  from  pthread_once(),  init_routine
       shall have completed. The once_control parameter shall determine whether the associated initialization routine has been called.

       The  pthread_once()  function  is not a cancellation point. However, if init_routine is a cancellation point and is canceled, the effect on
       once_control shall be as if pthread_once() was never called.

       The constant PTHREAD_ONCE_INIT is defined in the <pthread.h> header.

       The behavior of pthread_once() is undefined if once_control has automatic storage duration or is not initialized by PTHREAD_ONCE_INIT.

RETURN VALUE

       Upon successful completion, pthread_once() shall return zero; otherwise, an error number shall be returned to indicate the error.

ERRORS

       The pthread_once() function may fail if:

       EINVAL If either once_control or init_routine is invalid.

       The pthread_once() function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       Some C libraries are designed for dynamic initialization. That is, the global initialization for the library is performed  when	the  first
       procedure  in  the  library  is	called.  In a single-threaded program, this is normally implemented using a static variable whose value is
       checked on entry to a routine, as follows:

	      static int random_is_initialized = 0;
	      extern int initialize_random();

	      int random_function()
	      {
		  if (random_is_initialized == 0) {
		      initialize_random();
		      random_is_initialized = 1;
		  }
		  ... /* Operations performed after initialization. */
	      }

       To keep the same structure in a multi-threaded program, a new primitive is needed. Otherwise, library initialization has to be accomplished
       by an explicit call to a library-exported initialization function prior to any use of the library.

       For  dynamic  library initialization in a multi-threaded process, a simple initialization flag is not sufficient; the flag needs to be pro-
       tected against modification by multiple threads simultaneously calling into the library. Protecting the flag requires the use of  a  mutex;
       however,  mutexes  have to be initialized before they are used. Ensuring that the mutex is only initialized once requires a recursive solu-
       tion to this problem.

       The use of pthread_once() not only supplies an implementation-guaranteed means of dynamic initialization, it provides an aid to	the  reli-
       able construction of multi-threaded and realtime systems.  The preceding example then becomes:

	      #include <pthread.h>
	      static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT;
	      extern int initialize_random();

	      int random_function()
	      {
		  (void) pthread_once(&random_is_initialized, initialize_random);
		  ... /* Operations performed after initialization. */
	      }

       Note that a pthread_once_t cannot be an array because some compilers do not accept the construct &<array_name>.

FUTURE DIRECTIONS

       None.

SEE ALSO

       The Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
       ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE
       and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can  be  obtained
       online at http://www.opengroup.org/unix/online.html .

IEEE
/The Open Group						       2003							   PTHREAD_ONCE(P)