Technical Reference: Base Operating System and Extensions, Volume 1

pthread_once Subroutine

Purpose

Executes a routine exactly once in a process.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

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

pthread_once_t once_control = PTHREAD_ONCE_INIT;

Description

The pthread_once subroutine executes the routine init_routine exactly once in a process. The first call to this subroutine by any thread in the process executes the given routine, without parameters. Any subsequent call will have no effect.

The init_routine routine is typically an initialization routine. Multiple initializations can be handled by multiple instances of pthread_once_t structures. This subroutine is useful when a unique initialization has to be done by one thread among many. It reduces synchronization requirements.

Note

The pthread.h header file must be the first included file of each source file using the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

Parameters

once_control	Points to a synchronization control structure. This structure has to be initialized by the static initializer macro PTHREAD_ONCE_INIT.
init_routine	Points to the routine to be executed.

Return Values

Upon successful completion, pthread_once returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

No errors are defined. The pthread_once function will not return an error code of EINTR.

Related Information

The pthread_create (pthread_create Subroutine) subroutine, pthread.h file, PTHREAD_ONCE_INIT (PTHREAD_ONCE_INIT Macro) macro.

One Time Initializations in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Threads Library Quick Reference in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.