xpcom/base/nsIWeakReference.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   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 #include "nsISupports.idl"
   8
   9 %{C++
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/MemoryReporting.h"
  12
  13 // For MOZ_THREAD_SAFETY_OWNERSHIP_CHECKS_SUPPORTED.
  14 #include "nsDebug.h"
  15
  16 #ifdef MOZ_THREAD_SAFETY_OWNERSHIP_CHECKS_SUPPORTED
  17
  18 #define MOZ_WEAKREF_DECL_OWNINGTHREAD nsAutoOwningThread _mWeakRefOwningThread;
  19 #define MOZ_WEAKREF_ASSERT_OWNINGTHREAD \
  20   _mWeakRefOwningThread.AssertOwnership("nsWeakReference not thread-safe")
  21 #define MOZ_WEAKREF_ASSERT_OWNINGTHREAD_DELEGATED(that) \
  22   (that)->_mWeakRefOwningThread.AssertOwnership("nsWeakReference not thread-safe")
  23
  24 #else
  25
  26 #define MOZ_WEAKREF_DECL_OWNINGTHREAD
  27 #define MOZ_WEAKREF_ASSERT_OWNINGTHREAD do { } while (false)
  28 #define MOZ_WEAKREF_ASSERT_OWNINGTHREAD_DELEGATED(that) do { } while (false)
  29
  30 #endif
  31
  32 %}
  33
  34 /**
  35  * An instance of |nsIWeakReference| is a proxy object that cooperates with
  36  * its referent to give clients a non-owning, non-dangling reference.  Clients
  37  * own the proxy, and should generally manage it with an |nsCOMPtr| (see the
  38  * type |nsWeakPtr| for a |typedef| name that stands out) as they would any
  39  * other XPCOM object.  The |QueryReferent| member function provides a
  40  * (hopefully short-lived) owning reference on demand, through which clients
  41  * can get useful access to the referent, while it still exists.
  42  *
  43  * @version 1.0
  44  * @see nsISupportsWeakReference
  45  * @see nsWeakReference
  46  * @see nsWeakPtr
  47  */
  48 [scriptable, uuid(9188bc85-f92e-11d2-81ef-0060083a0bcf)]
  49 interface nsIWeakReference : nsISupports
  50   {
  51     /**
  52      * |QueryReferent| queries the referent, if it exists, and like |QueryInterface|, produces
  53      * an owning reference to the desired interface.  It is designed to look and act exactly
  54      * like (a proxied) |QueryInterface|.  Don't hold on to the produced interface permanently;
  55      * that would defeat the purpose of using a non-owning |nsIWeakReference| in the first place.
  56      */
  57     [binaryname(QueryReferentFromScript)]
  58     void QueryReferent( in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result );
  59
  60 %{C++
  61   virtual size_t SizeOfOnlyThis(mozilla::MallocSizeOf aMallocSizeOf) const = 0;
  62
  63   /**
  64    * Returns true if the referring object is alive.  Otherwise, false.
  65    */
  66   bool IsAlive() const
  67   {
  68     return !!mObject;
  69   }
  70
  71   nsresult QueryReferent(const nsIID& aIID, void** aInstancePtr);
  72
  73 protected:
  74   friend class nsSupportsWeakReference;
  75
  76   nsIWeakReference(nsISupports* aObject)
  77     : mObject(aObject)
  78   {
  79   }
  80
  81   nsIWeakReference() = delete;
  82
  83   MOZ_WEAKREF_DECL_OWNINGTHREAD
  84
  85   // The object we're holding a weak reference to.
  86   nsISupports* MOZ_NON_OWNING_REF mObject;
  87 %}
  88   };
  89
  90
  91 /**
  92  * |nsISupportsWeakReference| is a factory interface which produces appropriate
  93  * instances of |nsIWeakReference|.  Weak references in this scheme can only be
  94  * produced for objects that implement this interface.
  95  *
  96  * @version 1.0
  97  * @see nsIWeakReference
  98  * @see nsSupportsWeakReference
  99  */
 100 [scriptable, uuid(9188bc86-f92e-11d2-81ef-0060083a0bcf)]
 101 interface nsISupportsWeakReference : nsISupports
 102   {
 103     /**
 104      * |GetWeakReference| produces an appropriate instance of |nsIWeakReference|.
 105      * As with all good XPCOM `getters', you own the resulting interface and should
 106      * manage it with an |nsCOMPtr|.
 107      *
 108      * @see nsIWeakReference
 109      * @see nsWeakPtr
 110      * @see nsCOMPtr
 111      */
 112     nsIWeakReference GetWeakReference();
 113   };