]>
Commit | Line | Data |
---|---|---|
5f7b841d | 1 | /* Allocate and initialize an object once, in a thread-safe fashion. |
04277e02 | 2 | Copyright (C) 2018-2019 Free Software Foundation, Inc. |
5f7b841d FW |
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 | <http://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 */ |