run_once(9) [netbsd man page]

RUN_ONCE(9)						   BSD Kernel Developer's Manual					       RUN_ONCE(9)

NAME

     RUN_ONCE -- Run a function exactly once

SYNOPSIS

     #include <sys/once.h>

     ONCE_DECL(control);

     int
     RUN_ONCE(once_t *control, int (*init_func)(void));

DESCRIPTION

     RUN_ONCE() provides a functionality similar to pthread_once(3).  It ensures that, for a given control, init_func() is executed (successfully)
     exactly once.  It is considered as a successful execution if and only if init_func() returned 0.  As long as there was no successful execu-
     tion, RUN_ONCE() will try again each time it is called.

     RUN_ONCE() can sleep if it's called concurrently.

RETURN VALUES

     On failure, RUN_ONCE() returns what init_func() returned.	Otherwise, it returns 0.

EXAMPLES

     The following example shows how RUN_ONCE() is used.  Regardless of how many times some_func() is executed, init_func() will be executed
     exactly once.

     static int
     init_func(void)
     {

	     /*
	      * do some initialization.
	      */

	     return 0; /* success */
     }

     int
     some_func(void)
     {
	     static ONCE_DECL(control);

	     RUN_ONCE(&control, init_func);

	     /*
	      * we are sure that init_func has already been completed here.
	      */
     }

SEE ALSO

     pthread_once(3), condvar(9), intro(9)

BSD
								   July 7, 2010 							       BSD

pthread_once(3) 					     Library Functions Manual						   pthread_once(3)

NAME

       pthread_once - Calls a 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 	    (*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 controls the one-time execution code.  Each one-time execution routine must have its own unique pthread_once_t
       record.	Address of a procedure to be executed once.  This routine is called only once, regardless of the number of times it and its  asso-
       ciated 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  fin-
       ished.

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

ERRORS

       None

RELATED INFORMATION

       Manuals: Guide to DECthreads and Programmer's Guide

       delim off

																   pthread_once(3)