xpcom/base/nsISupportsUtils.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsISupportsUtils_h__
   8 #define nsISupportsUtils_h__
   9
  10 #include <type_traits>
  11
  12 #include "nscore.h"
  13 #include "nsISupportsBase.h"
  14 #include "nsError.h"
  15 #include "nsDebug.h"
  16 #include "nsISupportsImpl.h"
  17 #include "mozilla/RefPtr.h"
  18
  19 /**
  20  * Macro for adding a reference to an interface.
  21  * @param _ptr The interface pointer.
  22  */
  23 #define NS_ADDREF(_ptr) (_ptr)->AddRef()
  24
  25 /**
  26  * Macro for adding a reference to this. This macro should be used
  27  * because NS_ADDREF (when tracing) may require an ambiguous cast
  28  * from the pointers primary type to nsISupports. This macro sidesteps
  29  * that entire problem.
  30  */
  31 #define NS_ADDREF_THIS() AddRef()
  32
  33 // Making this a |inline| |template| allows |aExpr| to be evaluated only once,
  34 // yet still denies you the ability to |AddRef()| an |nsCOMPtr|.
  35 template <class T>
  36 inline void ns_if_addref(T aExpr) {
  37   if (aExpr) {
  38     aExpr->AddRef();
  39   }
  40 }
  41
  42 /**
  43  * Macro for adding a reference to an interface that checks for nullptr.
  44  * @param _expr The interface pointer.
  45  */
  46 #define NS_IF_ADDREF(_expr) ns_if_addref(_expr)
  47
  48 /*
  49  * Given these declarations, it explicitly OK and efficient to end a `getter'
  50  * with:
  51  *
  52  *    NS_IF_ADDREF(*result = mThing);
  53  *
  54  * even if |mThing| is an |nsCOMPtr|.  If |mThing| is an |nsCOMPtr|, however, it
  55  * is still _illegal_ to say |NS_IF_ADDREF(mThing)|.
  56  */
  57
  58 /**
  59  * Macro for releasing a reference to an interface.
  60  * @param _ptr The interface pointer.
  61  */
  62 #define NS_RELEASE(_ptr) \
  63   do {                   \
  64     (_ptr)->Release();   \
  65     (_ptr) = 0;          \
  66   } while (0)
  67
  68 /**
  69  * Macro for releasing a reference to this interface.
  70  */
  71 #define NS_RELEASE_THIS() Release()
  72
  73 /**
  74  * Macro for releasing a reference to an interface, except that this
  75  * macro preserves the return value from the underlying Release call.
  76  * The interface pointer argument will only be NULLed if the reference count
  77  * goes to zero.
  78  *
  79  * @param _ptr The interface pointer.
  80  * @param _rc  The reference count.
  81  */
  82 #define NS_RELEASE2(_ptr, _rc)  \
  83   do {                          \
  84     _rc = (_ptr)->Release();    \
  85     if (0 == (_rc)) (_ptr) = 0; \
  86   } while (0)
  87
  88 /**
  89  * Macro for releasing a reference to an interface that checks for nullptr;
  90  * @param _ptr The interface pointer.
  91  */
  92 #define NS_IF_RELEASE(_ptr) \
  93   do {                      \
  94     if (_ptr) {             \
  95       (_ptr)->Release();    \
  96       (_ptr) = 0;           \
  97     }                       \
  98   } while (0)
  99
 100 /*
 101  * Often you have to cast an implementation pointer, e.g., |this|, to an
 102  * |nsISupports*|, but because you have multiple inheritance, a simple cast
 103  * is ambiguous.  One could simply say, e.g., (given a base |nsIBase|),
 104  * |static_cast<nsIBase*>(this)|; but that disguises the fact that what
 105  * you are really doing is disambiguating the |nsISupports|.  You could make
 106  * that more obvious with a double cast, e.g., |static_cast<nsISupports*>
 107                                                            (*
 108  static_cast<nsIBase*>(this))|, but that is bulky and harder to read...
 109  *
 110  * The following macro is clean, short, and obvious.  In the example above,
 111  * you would use it like this: |NS_ISUPPORTS_CAST(nsIBase*, this)|.
 112  */
 113
 114 #define NS_ISUPPORTS_CAST(__unambiguousBase, __expr) \
 115   static_cast<nsISupports*>(static_cast<__unambiguousBase>(__expr))
 116
 117 // a type-safe shortcut for calling the |QueryInterface()| member function
 118 template <class T, class DestinationType>
 119 inline nsresult CallQueryInterface(T* aSource, DestinationType** aDestination) {
 120   // We permit nsISupports-to-nsISupports here so that one can still obtain
 121   // the canonical nsISupports pointer with CallQueryInterface.
 122   static_assert(
 123       !(std::is_same_v<DestinationType, T> ||
 124         std::is_base_of<DestinationType, T>::value) ||
 125           std::is_same_v<DestinationType, nsISupports>,
 126       "don't use CallQueryInterface for compile-time-determinable casts");
 127
 128   MOZ_ASSERT(aSource, "null parameter");
 129   MOZ_ASSERT(aDestination, "null parameter");
 130
 131   return aSource->QueryInterface(NS_GET_TEMPLATE_IID(DestinationType),
 132                                  reinterpret_cast<void**>(aDestination));
 133 }
 134
 135 template <class SourceType, class DestinationType>
 136 inline nsresult CallQueryInterface(RefPtr<SourceType>& aSourcePtr,
 137                                    DestinationType** aDestPtr) {
 138   return CallQueryInterface(aSourcePtr.get(), aDestPtr);
 139 }
 140
 141 #endif /* __nsISupportsUtils_h */