pthread_once()--Perform One-Time Initialization
Syntax:
#include <pthread.h> int pthread_once(pthread_once_t *once_control, void (*init_routine)(void));Service Program Name: QP0WPTHR
Default Public Authority: *USE
Threadsafe: Yes
Signal Safe: No
The pthread_once() function performs one time initialization based on a specific once_control variable. The init_routine is called only one time when multiple calls to pthread_once() use the same once_control.
The once_control variable is not set until the init_routine returns. If the init_routine is a cancellation point and the thread calling the init_routine by pthread_once() is cancelled, the once_control variable will not be set and a subsequent call to pthread_once() using that once_control variable will result in another call to the init_routine.
You must initialize the once_control variable to PTHREAD_ONCE_INIT prior to calling pthread_once() with it.
The function passed as init_routine must correspond to the following C function prototype:
void initRoutine(void);
Authorities and Locks
None.
Parameters
- once_control
- (Input) The control variable associated with this initialization.
- init_routine
- (Input) A function pointer to a routine that takes no parameters and returns no value.
Return Value
- 0
- pthread_once() was successful.
- value
- pthread_once() was not successful. value is set to indicate the error condition.
Error Conditions
If pthread_once() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.
- [EINVAL]
The value specified for the argument is not correct.
Related Information
- The <pthread.h> header file. See Header files for Pthread functions.
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#define _MULTI_THREADED #include <pthread.h> #include <stdio.h> #include "check.h" #define NUMTHREADS 3 int number = 0; int okStatus = 777; pthread_once_t onceControl = PTHREAD_ONCE_INIT; void initRoutine(void) { printf("In the initRoutine\n"); number++; } void *threadfunc(void *parm) { printf("Inside secondary thread\n"); pthread_once(&onceControl, initRoutine); return __VOID(okStatus); } int main(int argc, char **argv) { pthread_t thread[NUMTHREADS]; int rc=0; int i=NUMTHREADS; void *status; printf("Enter Testcase - %s\n", argv[0]); for (i=0; i < NUMTHREADS; ++i) { printf("Create thread %d\n", i); rc = pthread_create(&thread[i], NULL, threadfunc, NULL); checkResults("pthread_create()\n", rc); } for (i=0; i < NUMTHREADS; ++i) { printf("Wait for thread %d\n", i); rc = pthread_join(thread[i], &status); checkResults("pthread_join()\n", rc); if (__INT(status) != okStatus) { printf("Secondary thread failed\n"); exit(1); } } if (number != 1) { printf("An incorrect number of 1 one-time init routine was called!\n"); exit(1); } printf("One-time init routine called exactly once\n"); printf("Main completed\n"); return 0; }
Output:
Enter Testcase - QP0WTEST/TPONCE0 Create thread 0 Create thread 1 Create thread 2 Wait for thread 0 Inside secondary thread In the initRoutine Inside secondary thread Wait for thread 1 Wait for thread 2 Inside secondary thread One-time init routine called exactly once Main completed
API introduced: V4R3
[ Back to top | Pthread APIs | APIs by category ]