summaryrefslogtreecommitdiffstats
path: root/memory/fallible/fallible.h
diff options
context:
space:
mode:
Diffstat (limited to 'memory/fallible/fallible.h')
-rw-r--r--memory/fallible/fallible.h68
1 files changed, 68 insertions, 0 deletions
diff --git a/memory/fallible/fallible.h b/memory/fallible/fallible.h
new file mode 100644
index 000000000..c028360b1
--- /dev/null
+++ b/memory/fallible/fallible.h
@@ -0,0 +1,68 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef mozilla_fallible_h
+#define mozilla_fallible_h
+
+#if defined(__cplusplus)
+
+/* Explicit fallible allocation
+ *
+ * Memory allocation (normally) defaults to abort in case of failed
+ * allocation. That is, it never returns NULL, and crashes instead.
+ *
+ * Code can explicitely request for fallible memory allocation thanks
+ * to the declarations below.
+ *
+ * The typical use of the mozilla::fallible const is with placement new,
+ * like the following:
+ *
+ * foo = new (mozilla::fallible) Foo();
+ *
+ * The following forms, or derivatives, are also possible but deprecated:
+ *
+ * foo = new ((mozilla::fallible_t())) Foo();
+ *
+ * const mozilla::fallible_t fallible = mozilla::fallible_t();
+ * bar = new (f) Bar();
+ *
+ * It is also possible to declare method overloads with fallible allocation
+ * alternatives, like so:
+ *
+ * class Foo {
+ * public:
+ * void Method(void *);
+ * void Method(void *, const mozilla::fallible_t&);
+ * };
+ *
+ * Foo foo;
+ * foo.Method(nullptr, mozilla::fallible);
+ *
+ * If that last method call is in a method that itself takes a const
+ * fallible_t& argument, it is recommended to propagate that argument
+ * instead of using mozilla::fallible:
+ *
+ * void Func(Foo &foo, const mozilla::fallible_t& aFallible) {
+ * foo.Method(nullptr, aFallible);
+ * }
+ *
+ */
+namespace mozilla {
+
+struct fallible_t { };
+
+/* This symbol is kept unexported, such that in corner cases where the
+ * compiler can't remove its use (essentially, cross compilation-unit
+ * calls), the smallest machine code is used.
+ * Depending how the linker packs symbols, it will consume between 1 and
+ * 8 bytes of read-only data in each executable or shared library, but
+ * only in those where it's actually not optimized out by the compiler.
+ */
+extern const fallible_t fallible;
+
+} // namespace mozilla
+
+#endif
+
+#endif // mozilla_fallible_h