1  /* Allocate and initialize an object once, in a thread-safe fashion.
       2     Copyright (C) 2018-2023 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 */