1/* Allocate and initialize an object once, in a thread-safe fashion.
2 Copyright (C) 2018-2022 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
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. */
76static inline void *
77allocate_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
92libc_hidden_proto (__libc_allocate_once_slow)
93#endif
94
95#endif /* _ALLOCATE_ONCE_H */
96