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. */
25void *__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
31libc_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. */
79static inline void *
80allocate_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 */
95