xref: /titanic_50/usr/src/man/man3c/call_once.3c (revision dcdfe824b3dff2df12578b936adf1daf000aa129)
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