summaryrefslogtreecommitdiff
path: root/include/allocate_once.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/allocate_once.h')
-rw-r--r--include/allocate_once.h95
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 */