1*dcdfe824SRobert Mustacchi.\" 2*dcdfe824SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*dcdfe824SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*dcdfe824SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*dcdfe824SRobert Mustacchi.\" 1.0 of the CDDL. 6*dcdfe824SRobert Mustacchi.\" 7*dcdfe824SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*dcdfe824SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*dcdfe824SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*dcdfe824SRobert Mustacchi.\" 11*dcdfe824SRobert Mustacchi.\" 12*dcdfe824SRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 13*dcdfe824SRobert Mustacchi.\" 14*dcdfe824SRobert Mustacchi.Dd "Jan 11, 2015" 15*dcdfe824SRobert Mustacchi.Dt CALL_ONCE 3C 16*dcdfe824SRobert Mustacchi.Os 17*dcdfe824SRobert Mustacchi.Sh NAME 18*dcdfe824SRobert Mustacchi.Nm call_once 19*dcdfe824SRobert Mustacchi.Nd ensure function is only called once 20*dcdfe824SRobert Mustacchi.Sh SYNOPSIS 21*dcdfe824SRobert Mustacchi.In treads.h 22*dcdfe824SRobert Mustacchi.Vt "once_flag once = ONCE_FLAG_INIT;" 23*dcdfe824SRobert Mustacchi.Ft void 24*dcdfe824SRobert Mustacchi.Fo call_once 25*dcdfe824SRobert Mustacchi.Fa "once_flag *once" 26*dcdfe824SRobert Mustacchi.Fa "void (*func)(void)" 27*dcdfe824SRobert Mustacchi.Fc 28*dcdfe824SRobert Mustacchi.Sh DESCRIPTION 29*dcdfe824SRobert MustacchiThe 30*dcdfe824SRobert Mustacchi.Fn call_once 31*dcdfe824SRobert Mustacchifunction is used to ensure that an operation occurs only once, even 32*dcdfe824SRobert Mustacchiacross multiple threads. Each instance of a properly initialized 33*dcdfe824SRobert Mustacchi.Ft once_flag 34*dcdfe824SRobert Mustacchican be pased to the 35*dcdfe824SRobert Mustacchi.Ft call_once 36*dcdfe824SRobert Mustacchifunction; however, only a single caller will successfully execute the 37*dcdfe824SRobert Mustacchispecified function, 38*dcdfe824SRobert Mustacchi.Fa func . 39*dcdfe824SRobert MustacchiThis ensures that the argument 40*dcdfe824SRobert Mustacchi.Fa func 41*dcdfe824SRobert Mustacchiis called only once. Note, the argument 42*dcdfe824SRobert Mustacchi.Fa once 43*dcdfe824SRobert Mustacchiis the only thing used as a point of synchronization. If multiple 44*dcdfe824SRobert Mustacchicallers use the same pointer for 45*dcdfe824SRobert Mustacchi.Fa once , 46*dcdfe824SRobert Mustacchibut use different values for 47*dcdfe824SRobert Mustacchi.Fa func , 48*dcdfe824SRobert Mustacchithen only one of the functions will be successfully called. 49*dcdfe824SRobert Mustacchi.Pp 50*dcdfe824SRobert MustacchiThe argument 51*dcdfe824SRobert Mustacchi.Fn once 52*dcdfe824SRobert Mustacchishould always be initialized to the symbol 53*dcdfe824SRobert Mustacchi.Sy ONCE_FLAG_INIT 54*dcdfe824SRobert Mustacchibefore calling 55*dcdfe824SRobert Mustacchi.Fn call_once . 56*dcdfe824SRobert MustacchiFailure to do so will result in undefined behavior. 57*dcdfe824SRobert Mustacchi.Pp 58*dcdfe824SRobert MustacchiLike 59*dcdfe824SRobert Mustacchi.Xr pthread_once 3C , 60*dcdfe824SRobert Mustacchithe 61*dcdfe824SRobert Mustacchi.Fn call_once 62*dcdfe824SRobert Mustacchifunction is not itself a cancellation point; however, if the thread 63*dcdfe824SRobert Mustacchicalling 64*dcdfe824SRobert Mustacchi.Fn func 65*dcdfe824SRobert Mustacchiencounters a cancellation point and is cancelled, then the value pointed 66*dcdfe824SRobert Mustacchito by 67*dcdfe824SRobert Mustacchi.Fa once 68*dcdfe824SRobert Mustacchiwill be as though 69*dcdfe824SRobert Mustacchi.Fn call_once 70*dcdfe824SRobert Mustacchihad not been called, as 71*dcdfe824SRobert Mustacchi.Fn func 72*dcdfe824SRobert Mustacchihad not completed successfully. 73*dcdfe824SRobert Mustacchi.Sh RETURN VALUES 74*dcdfe824SRobert MustacchiThe 75*dcdfe824SRobert Mustacchi.Fn call_once 76*dcdfe824SRobert Mustacchifunction does not return any values. Upon its completion, it is guaranteed that 77*dcdfe824SRobert Mustacchi.Fa func 78*dcdfe824SRobert Mustacchiwill have been called at most once across the liftime of the 79*dcdfe824SRobert Mustacchi.Fa once 80*dcdfe824SRobert Mustacchiargument . 81*dcdfe824SRobert Mustacchi.Sh INTERFACE STABILITY 82*dcdfe824SRobert Mustacchi.Sy Standard 83*dcdfe824SRobert Mustacchi.Sh MT-LEVEL 84*dcdfe824SRobert Mustacchi.Sy MT-Safe 85*dcdfe824SRobert Mustacchi.Sh SEE ALSO 86*dcdfe824SRobert Mustacchi.Xr pthread_once 3C , 87*dcdfe824SRobert Mustacchi.Xr threads.h 3HEAD , 88*dcdfe824SRobert Mustacchi.Xr attributes 5 , 89*dcdfe824SRobert Mustacchi.Xr threads 5 90