diff options
Diffstat (limited to 'include/allocate_once.h')
| -rw-r--r-- | include/allocate_once.h | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/include/allocate_once.h b/include/allocate_once.h new file mode 100644 index 0000000000..26902dde7c --- /dev/null +++ b/include/allocate_once.h @@ -0,0 +1,95 @@ +/* Allocate and initialize an object once, in a thread-safe fashion. + Copyright (C) 2018 Free Software Foundation, Inc. + This file is part of the GNU C Library. + + The GNU C Library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + The GNU C Library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with the GNU C Library; if not, see + <http://www.gnu.org/licenses/>. */ + +#ifndef _ALLOCATE_ONCE_H +#define _ALLOCATE_ONCE_H + +#include <atomic.h> + +/* Slow path for allocate_once; see below. */ +void *__libc_allocate_once_slow (void **__place, + void *(*__allocate) (void *__closure), + void (*__deallocate) (void *__closure, + void *__ptr), + void *__closure); + +/* Return an a pointer to an allocated and initialized data structure. + If this function returns a non-NULL value, the caller can assume + that pointed-to data has been initialized according to the ALLOCATE + function. + + It is expected that callers define an inline helper function which + adds type safety, like this. + + struct foo { ... }; + struct foo *global_foo; + static void *allocate_foo (void *closure); + static void *deallocate_foo (void *closure, void *ptr); + + static inline struct foo * + get_foo (void) + { + return allocate_once (&global_foo, allocate_foo, free_foo, NULL); + } + + (Note that the global_foo variable is initialized to zero.) + Usage of this helper function looks like this: + + struct foo *local_foo = get_foo (); + if (local_foo == NULL) + report_allocation_failure (); + + allocate_once first performs an acquire MO load on *PLACE. If the + result is not null, it is returned. Otherwise, ALLOCATE (CLOSURE) + is called, yielding a value RESULT. If RESULT equals NULL, + allocate_once returns NULL, and does not modify *PLACE (but another + thread may concurrently perform an allocation which succeeds, + updating *PLACE). If RESULT does not equal NULL, the function uses + a CAS with acquire-release MO to update the NULL value in *PLACE + with the RESULT value. If it turns out that *PLACE was updated + concurrently, allocate_once calls DEALLOCATE (CLOSURE, RESULT) to + undo the effect of ALLOCATE, and returns the new value of *PLACE + (after an acquire MO load). If DEALLOCATE is NULL, free (RESULT) + is called instead. + + Compared to __libc_once, allocate_once has the advantage that it + does not need separate space for a control variable, and that it is + safe with regards to cancellation and other forms of exception + handling if the supplied callback functions are safe in that + regard. allocate_once passes a closure parameter to the allocation + function, too. */ +static inline void * +allocate_once (void **__place, void *(*__allocate) (void *__closure), + void (*__deallocate) (void *__closure, void *__ptr), + void *__closure) +{ + /* Synchronizes with the release MO CAS in + __allocate_once_slow. */ + void *__result = atomic_load_acquire (__place); + if (__result != NULL) + return __result; + else + return __libc_allocate_once_slow (__place, __allocate, __deallocate, + __closure); +} + +#ifndef _ISOMAC +libc_hidden_proto (__libc_allocate_once_slow) +#endif + +#endif /* _ALLOCATE_ONCE_H */ |