mfbt/fallible.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef mozilla_fallible_h
   6 #define mozilla_fallible_h
   7
   8 #if defined(__cplusplus)
   9
  10 /* Explicit fallible allocation
  11  *
  12  * Memory allocation (normally) defaults to abort in case of failed
  13  * allocation. That is, it never returns NULL, and crashes instead.
  14  *
  15  * Code can explicitely request for fallible memory allocation thanks
  16  * to the declarations below.
  17  *
  18  * The typical use of the mozilla::fallible const is with placement new,
  19  * like the following:
  20  *
  21  *     foo = new (mozilla::fallible) Foo();
  22  *
  23  * The following forms, or derivatives, are also possible but deprecated:
  24  *
  25  *     foo = new ((mozilla::fallible_t())) Foo();
  26  *
  27  *     const mozilla::fallible_t f = mozilla::fallible_t();
  28  *     bar = new (f) Bar();
  29  *
  30  * It is also possible to declare method overloads with fallible allocation
  31  * alternatives, like so:
  32  *
  33  *     class Foo {
  34  *     public:
  35  *       void Method(void *);
  36  *       void Method(void *, const mozilla::fallible_t&);
  37  *     };
  38  *
  39  *     Foo foo;
  40  *     foo.Method(nullptr, mozilla::fallible);
  41  *
  42  * If that last method call is in a method that itself takes a const
  43  * fallible_t& argument, it is recommended to propagate that argument
  44  * instead of using mozilla::fallible:
  45  *
  46  *     void Func(Foo &foo, const mozilla::fallible_t& aFallible) {
  47  *         foo.Method(nullptr, aFallible);
  48  *     }
  49  *
  50  */
  51
  52 #  include <new>
  53
  54 namespace mozilla {
  55
  56 using fallible_t = std::nothrow_t;
  57
  58 static const fallible_t& fallible = std::nothrow;
  59
  60 }  // namespace mozilla
  61
  62 #endif
  63
  64 #endif  // mozilla_fallible_h