include/allocate_once.h

   1 /* Allocate and initialize an object once, in a thread-safe fashion.
   2    Copyright (C) 2018-2021 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _ALLOCATE_ONCE_H
  20 #define _ALLOCATE_ONCE_H
  21
  22 #include <atomic.h>
  23
  24 /* Slow path for allocate_once; see below.  */
  25 void *__libc_allocate_once_slow (void **__place,
  26                                  void *(*__allocate) (void *__closure),
  27                                  void (*__deallocate) (void *__closure,
  28                                                        void *__ptr),
  29                                  void *__closure);
  30
  31 /* Return an a pointer to an allocated and initialized data structure.
  32    If this function returns a non-NULL value, the caller can assume
  33    that pointed-to data has been initialized according to the ALLOCATE
  34    function.
  35
  36    It is expected that callers define an inline helper function which
  37    adds type safety, like this.
  38
  39    struct foo { ... };
  40    struct foo *global_foo;
  41    static void *allocate_foo (void *closure);
  42    static void *deallocate_foo (void *closure, void *ptr);
  43
  44    static inline struct foo *
  45    get_foo (void)
  46    {
  47      return allocate_once (&global_foo, allocate_foo, free_foo, NULL);
  48    }
  49
  50    (Note that the global_foo variable is initialized to zero.)
  51    Usage of this helper function looks like this:
  52
  53    struct foo *local_foo = get_foo ();
  54    if (local_foo == NULL)
  55       report_allocation_failure ();
  56
  57    allocate_once first performs an acquire MO load on *PLACE.  If the
  58    result is not null, it is returned.  Otherwise, ALLOCATE (CLOSURE)
  59    is called, yielding a value RESULT.  If RESULT equals NULL,
  60    allocate_once returns NULL, and does not modify *PLACE (but another
  61    thread may concurrently perform an allocation which succeeds,
  62    updating *PLACE).  If RESULT does not equal NULL, the function uses
  63    a CAS with acquire-release MO to update the NULL value in *PLACE
  64    with the RESULT value.  If it turns out that *PLACE was updated
  65    concurrently, allocate_once calls DEALLOCATE (CLOSURE, RESULT) to
  66    undo the effect of ALLOCATE, and returns the new value of *PLACE
  67    (after an acquire MO load).  If DEALLOCATE is NULL, free (RESULT)
  68    is called instead.
  69
  70    Compared to __libc_once, allocate_once has the advantage that it
  71    does not need separate space for a control variable, and that it is
  72    safe with regards to cancellation and other forms of exception
  73    handling if the supplied callback functions are safe in that
  74    regard.  allocate_once passes a closure parameter to the allocation
  75    function, too.  */
  76 static inline void *
  77 allocate_once (void **__place, void *(*__allocate) (void *__closure),
  78                void (*__deallocate) (void *__closure, void *__ptr),
  79                void *__closure)
  80 {
  81   /* Synchronizes with the release MO CAS in
  82      __allocate_once_slow.  */
  83   void *__result = atomic_load_acquire (__place);
  84   if (__result != NULL)
  85     return __result;
  86   else
  87     return __libc_allocate_once_slow (__place, __allocate, __deallocate,
  88                                       __closure);
  89 }
  90
  91 #ifndef _ISOMAC
  92 libc_hidden_proto (__libc_allocate_once_slow)
  93 #endif
  94
  95 #endif /* _ALLOCATE_ONCE_H */