man/dispatch_once.3

   1 .\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
   2 .Dd May 1, 2009
   3 .Dt dispatch_once 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_once
   7 .Nd execute a block only once
   8 .Sh SYNOPSIS
   9 .Fd #include <dispatch/dispatch.h>
  10 .Ft void
  11 .Fo dispatch_once
  12 .Fa "dispatch_once_t *predicate" "void (^block)(void)"
  13 .Fc
  14 .Ft void
  15 .Fo dispatch_once_f
  16 .Fa "dispatch_once_t *predicate" "void *context" "void (*function)(void *)"
  17 .Fc
  18 .Sh DESCRIPTION
  19 The
  20 .Fn dispatch_once
  21 function provides a simple and efficient mechanism to run an initializer
  22 exactly once, similar to
  23 .Xr pthread_once 3 .
  24 Well designed code hides the use of lazy initialization.
  25 For example:
  26 .Bd -literal
  27 FILE *getlogfile(void)
  28 {
  29         static dispatch_once_t pred;
  30         static FILE *logfile;
  31
  32         dispatch_once(&pred, ^{
  33                 logfile = fopen(MY_LOG_FILE, "a");
  34         });
  35
  36         return logfile;
  37 }
  38 .Ed
  39 .Pp
  40 .Sh FUNDAMENTALS
  41 The
  42 .Fn dispatch_once
  43 function is a wrapper around
  44 .Fn dispatch_once_f .
  45 .Sh SEE ALSO
  46 .Xr dispatch 3