Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 1

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 1

Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 8

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 8

pthread_once()

Dynamic package initialization

Synopsis:

#include <pthread.h>

pthread_once_t once_control = PTHREAD_ONCE_INIT;

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

Arguments:

once_control
A pointer to a pthread_once_t object that the function uses to determine whether or not to run the initialization code.

Note: You must set the pthread_once_t object to the macro PTHREAD_ONCE_INIT before using it for the first time.

init_routine
The function that you want to call to do any required initialization.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_once() function uses the once-control object once_control to determine whether the initialization routine init_routine should be called.


Caution: You should allocate the control object only in normal memory mappings. Doing otherwise will cause a fault on certain processors (e.g. some PPC ones).

The first call to pthread_once() by any thread in a process, with a given once_control, calls init_routine with no arguments. Subsequent calls of pthread_once() with the same once_control won't call init_routine.


Note: No thread will execute past this function until the init_routine returns.

Returns:

EOK
Success.
EINVAL
Uninitialized once-control object once_control.

Examples:

This example shows how you can use once-initialization to initialize a library; both library_entry_point1() and library_entry_point2() need to initialize the library, but that needs to happen only once:

#include <stdio.h>
#include <pthread.h>

pthread_once_t once_control = PTHREAD_ONCE_INIT;

void library_init( void )
{
    /* initialize the library */
}

void library_entry_point1( void )
{
    pthread_once( &once_control, library_init );
    
    /* do stuff for library_entry_point1... */
}

void library_entry_point2( void )
{
    pthread_once( &once_control, library_init );
    
    /* do stuff for library_entry_point1... */
}

This initializes the library once; if multiple threads call pthread_once(), only one actually enters the library_init() function. The other threads block at the pthread_once() call until library_init() has returned. The pthread_once() function also ensures that library_init() is only ever called once; subsequent calls to the library entry points skip the call to library_init().

Classification:

POSIX 1003.1 THR

Safety:
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 207

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_once.html on line 207