Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > P

pthread_once(3T)

Pthread Library
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

pthread_once() — call an initialization routine only once

SYNOPSIS

#include <pthread.h>

pthread_once_t once_control = PTHREAD_ONCE_INIT;

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

Parameters

once_control

Pointer to the once-control object associated with the one-time initialization function init_routine().

init_routine

The one-time initialization routine. This routine is called only once, regardless of the number of times it and its associated once_control are passed to pthread_once().

DESCRIPTION

The pthread_once() function guarantees that init_routine() is only called one time in an application. This function will use the once_control object to determine if init_routine() has previously been called via pthread_once().

The first time pthread_once() is called with once_control and init_routine() causes init_routine() to be called with no arguments. Subsequent calls to pthread_once() with the same once_control will not cause init_routine() to be called again. When pthread_once() returns, the caller is guaranteed that init_routine() has been called (either just now or via a previous call).

The macro PTHREAD_ONCE_INIT is used to statically initialize a once control block. This initialization must be done before calling pthread_once().

pthread_once() is not a cancellation point. However, the caller supplied init_routine() may be a cancellation point. If the thread executing init_routine() is canceled, the once_control argument will be set to a state which indicates that init_routine() has not been called yet (see pthread_cancel(3T)). The next time the pthread_once() function is called with once_control, the init_routine() function will be called.

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

RETURN VALUE

pthread_once() returns returns the following values:

0

Successful completion.

<>0

Failure. An error number is returned to indicate the error. (The errno variable is not set.)

ERRORS

The following error value is returned by pthread_once() if the corresponding condition is detected.

EINVAL

Either once_control or init_routine is invalid.

EXAMPLES

Some modules are designed for dynamic initialization, i.e., global initialization is performed when the first function of the module is invoked. In a single-threaded program, this is generally implemented as follows:

static int initialized = FALSE; extern void initialize(); if (!initialized) { initialize(); initialized = TRUE; } (Rest of the code after initialization.)

For a multithreaded process, a simple initialization flag is not sufficient; the flag must be protected against modification by multiple threads. Consequently, this flag has to be protected by a mutex that has to be initialized only once, and so on. A multithreaded program should use initialization similar to:

static pthread_once_t once_control = PTHREAD_ONCE_INIT; extern void initialize(); (void)pthread_once(&once_control, initialize); (Rest of the code after initialization.)

AUTHOR

pthread_once() was derived from the IEEE POSIX P1003.1c standard.

STANDARDS CONFORMANCE

pthread_once(): POSIX 1003.1c.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.