share/man/man9/RUN_ONCE.9

   1 .\"     $NetBSD: RUN_ONCE.9,v 1.6 2007/07/14 10:52:47 ad Exp $
   2 .\"
   3 .\" Copyright (c)2005 YAMAMOTO Takashi,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" ------------------------------------------------------------
  28 .Dd October 3, 2008
  29 .Dt RUN_ONCE 9
  30 .Os
  31 .\" ------------------------------------------------------------
  32 .Sh NAME
  33 .Nm RUN_ONCE
  34 .Nd Run a function exactly once
  35 .\" ------------------------------------------------------------
  36 .Sh SYNOPSIS
  37 .In sys/once.h
  38 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  39 .Vt ONCE_DECL(control);
  40 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  41 .Ft int
  42 .Fn RUN_ONCE \
  43 "once_t *control" "int (*init_func)(void)"
  44 .\" ------------------------------------------------------------
  45 .Sh DESCRIPTION
  46 .Fn RUN_ONCE
  47 provides a functionality similar to
  48 .Fn pthread_once 3 .
  49 It ensures that, for a given
  50 .Fa control ,
  51 .Fn init_func
  52 is executed (successfully) exactly once.
  53 It is considered as a successful execution if and only if
  54 .Fn init_func
  55 returned 0.
  56 As long as there was no successful execution,
  57 .Fn RUN_ONCE
  58 will try again each time it is called.
  59 .Pp
  60 .Fn RUN_ONCE
  61 can sleep if it's called concurrently.
  62 .\" ------------------------------------------------------------
  63 .Sh RETURN VALUES
  64 On failure,
  65 .Fn RUN_ONCE
  66 returns what
  67 .Fn init_func
  68 returned.
  69 Otherwise, it returns 0.
  70 .\" ------------------------------------------------------------
  71 .Sh EXAMPLES
  72 The following example shows how
  73 .Fn RUN_ONCE
  74 is used.
  75 Regardless of how many times
  76 .Fn some_func
  77 is executed,
  78 .Fn init_func
  79 will be executed exactly once.
  80 .Bd -literal
  81 static int
  82 init_func(void)
  83 {
  84
  85         /*
  86          * do some initialization.
  87          */
  88
  89         return 0; /* success */
  90 }
  91
  92 int
  93 some_func(void)
  94 {
  95         static ONCE_DECL(control);
  96
  97         RUN_ONCE(\*[Am]control, init_func);
  98
  99         /*
 100          * we are sure that init_func has already been completed here.
 101          */
 102 }
 103 .Ed
 104 .\" ------------------------------------------------------------
 105 .Sh SEE ALSO
 106 .Xr pthread_once 3 ,
 107 .Xr condvar 9 ,
 108 .Xr intro 9