[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, 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 (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_block 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.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_create subroutine, pthread.h file, PTHREAD_ONCE_INIT macro.

One Time Initializations in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

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


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]