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
Check Out this Related Man Page
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)