share/man/man3c/call_once.3c

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