include/allocate_once.h

   1 /* Allocate and initialize an object once, in a thread-safe fashion.
   2    Copyright (C) 2018-2024 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 #ifndef _ISOMAC
  31 libc_hidden_proto (__libc_allocate_once_slow)
  32 #endif
  33
  34 /* Return an a pointer to an allocated and initialized data structure.
  35    If this function returns a non-NULL value, the caller can assume
  36    that pointed-to data has been initialized according to the ALLOCATE
  37    function.
  38
  39    It is expected that callers define an inline helper function which
  40    adds type safety, like this.
  41
  42    struct foo { ... };
  43    struct foo *global_foo;
  44    static void *allocate_foo (void *closure);
  45    static void *deallocate_foo (void *closure, void *ptr);
  46
  47    static inline struct foo *
  48    get_foo (void)
  49    {
  50      return allocate_once (&global_foo, allocate_foo, free_foo, NULL);
  51    }
  52
  53    (Note that the global_foo variable is initialized to zero.)
  54    Usage of this helper function looks like this:
  55
  56    struct foo *local_foo = get_foo ();
  57    if (local_foo == NULL)
  58       report_allocation_failure ();
  59
  60    allocate_once first performs an acquire MO load on *PLACE.  If the
  61    result is not null, it is returned.  Otherwise, ALLOCATE (CLOSURE)
  62    is called, yielding a value RESULT.  If RESULT equals NULL,
  63    allocate_once returns NULL, and does not modify *PLACE (but another
  64    thread may concurrently perform an allocation which succeeds,
  65    updating *PLACE).  If RESULT does not equal NULL, the function uses
  66    a CAS with acquire-release MO to update the NULL value in *PLACE
  67    with the RESULT value.  If it turns out that *PLACE was updated
  68    concurrently, allocate_once calls DEALLOCATE (CLOSURE, RESULT) to
  69    undo the effect of ALLOCATE, and returns the new value of *PLACE
  70    (after an acquire MO load).  If DEALLOCATE is NULL, free (RESULT)
  71    is called instead.
  72
  73    Compared to __libc_once, allocate_once has the advantage that it
  74    does not need separate space for a control variable, and that it is
  75    safe with regards to cancellation and other forms of exception
  76    handling if the supplied callback functions are safe in that
  77    regard.  allocate_once passes a closure parameter to the allocation
  78    function, too.  */
  79 static inline void *
  80 allocate_once (void **__place, void *(*__allocate) (void *__closure),
  81                void (*__deallocate) (void *__closure, void *__ptr),
  82                void *__closure)
  83 {
  84   /* Synchronizes with the release MO CAS in
  85      __allocate_once_slow.  */
  86   void *__result = atomic_load_acquire (__place);
  87   if (__result != NULL)
  88     return __result;
  89   else
  90     return __libc_allocate_once_slow (__place, __allocate, __deallocate,
  91                                       __closure);
  92 }
  93
  94 #endif /* _ALLOCATE_ONCE_H */