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 native MallocSizeOf(mozilla::MallocSizeOf);
  35
  36 /**
  37  * An instance of |nsIWeakReference| is a proxy object that cooperates with
  38  * its referent to give clients a non-owning, non-dangling reference.  Clients
  39  * own the proxy, and should generally manage it with an |nsCOMPtr| (see the
  40  * type |nsWeakPtr| for a |typedef| name that stands out) as they would any
  41  * other XPCOM object.  The |QueryReferent| member function provides a
  42  * (hopefully short-lived) owning reference on demand, through which clients
  43  * can get useful access to the referent, while it still exists.
  44  *
  45  * @version 1.0
  46  * @see nsISupportsWeakReference
  47  * @see nsWeakReference
  48  * @see nsWeakPtr
  49  */
  50 [scriptable, builtinclass, uuid(9188bc85-f92e-11d2-81ef-0060083a0bcf)]
  51 interface nsIWeakReference : nsISupports
  52   {
  53     /**
  54      * |QueryReferent| queries the referent, if it exists, and like |QueryInterface|, produces
  55      * an owning reference to the desired interface.  It is designed to look and act exactly
  56      * like (a proxied) |QueryInterface|.  Don't hold on to the produced interface permanently;
  57      * that would defeat the purpose of using a non-owning |nsIWeakReference| in the first place.
  58      */
  59     [binaryname(QueryReferentFromScript)]
  60     void QueryReferent( in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result );
  61
  62     [notxpcom, nostdcall] size_t sizeOfOnlyThis(in MallocSizeOf aMallocSizeOf);
  63 %{C++
  64   /**
  65    * Returns true if the referring object is alive.  Otherwise, false.
  66    */
  67   bool IsAlive() const
  68   {
  69     return !!mObject;
  70   }
  71
  72   nsresult QueryReferent(const nsIID& aIID, void** aInstancePtr);
  73
  74 protected:
  75   friend class nsSupportsWeakReference;
  76
  77   nsIWeakReference(nsISupports* aObject)
  78     : mObject(aObject)
  79   {
  80   }
  81
  82   nsIWeakReference() = delete;
  83
  84   MOZ_WEAKREF_DECL_OWNINGTHREAD
  85
  86   // The object we're holding a weak reference to.
  87   nsISupports* MOZ_NON_OWNING_REF mObject;
  88 %}
  89   };
  90
  91
  92 /**
  93  * |nsISupportsWeakReference| is a factory interface which produces appropriate
  94  * instances of |nsIWeakReference|.  Weak references in this scheme can only be
  95  * produced for objects that implement this interface.
  96  *
  97  * @version 1.0
  98  * @see nsIWeakReference
  99  * @see nsSupportsWeakReference
 100  */
 101 [scriptable, uuid(9188bc86-f92e-11d2-81ef-0060083a0bcf)]
 102 interface nsISupportsWeakReference : nsISupports
 103   {
 104     /**
 105      * |GetWeakReference| produces an appropriate instance of |nsIWeakReference|.
 106      * As with all good XPCOM `getters', you own the resulting interface and should
 107      * manage it with an |nsCOMPtr|.
 108      *
 109      * @see nsIWeakReference
 110      * @see nsWeakPtr
 111      * @see nsCOMPtr
 112      */
 113     nsIWeakReference GetWeakReference();
 114   };