include/cppuhelper/weakref.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23 #ifndef INCLUDED_CPPUHELPER_WEAKREF_HXX
  24 #define INCLUDED_CPPUHELPER_WEAKREF_HXX
  25
  26 #include "sal/config.h"
  27
  28 #include <cstddef>
  29
  30 #include "com/sun/star/uno/Reference.hxx"
  31 #include "com/sun/star/uno/XInterface.hpp"
  32 #include "cppuhelper/cppuhelperdllapi.h"
  33
  34
  35 namespace com
  36 {
  37 namespace sun
  38 {
  39 namespace star
  40 {
  41 namespace uno
  42 {
  43
  44 class OWeakRefListener;
  45 class XWeak;
  46
  47 /** The WeakReferenceHelper holds a weak reference to an object.
  48
  49     That object must implement the css::uno::XWeak interface.
  50
  51     The WeakReferenceHelper itself is *not* thread safe, just as
  52     Reference itself isn't, but the implementation of the listeners etc.
  53     behind it *is* thread-safe, so multiple threads can have their own
  54     WeakReferences to the same XWeak object.
  55 */
  56 class CPPUHELPER_DLLPUBLIC WeakReferenceHelper
  57 {
  58 public:
  59     /** Default ctor.  Creates an empty weak reference.
  60     */
  61     WeakReferenceHelper()
  62         : m_pImpl( NULL )
  63         {}
  64
  65     /** Copy ctor.  Initialize this reference with the same interface as in rWeakRef.
  66
  67         @param rWeakRef another weak ref
  68     */
  69     WeakReferenceHelper( const WeakReferenceHelper & rWeakRef );
  70
  71 #if defined LIBO_INTERNAL_ONLY
  72     WeakReferenceHelper(WeakReferenceHelper && other) noexcept : m_pImpl(other.m_pImpl)
  73     { other.m_pImpl = nullptr; }
  74 #endif
  75
  76     /** Initialize this reference with the hard interface reference xInt. If the implementation
  77         behind xInt does not support XWeak or xInt is null then this reference will be null.
  78
  79         @param xInt another hard interface reference
  80     */
  81     WeakReferenceHelper( const css::uno::Reference< css::uno::XInterface > & xInt );
  82
  83 #if defined LIBO_INTERNAL_ONLY
  84     /** Initialize this reference with the hard interface reference xWeak. This
  85          is faster than the XInterface constructor because we can skip doing an
  86          UNO_QUERY.
  87
  88         @param xWeak another hard interface reference
  89     */
  90     WeakReferenceHelper( const css::uno::Reference< css::uno::XWeak > & xWeak );
  91 #endif
  92
  93     /** Releases this reference.
  94     */
  95     ~WeakReferenceHelper();
  96
  97     /** Releases this reference and takes over rWeakRef.
  98
  99         @param rWeakRef another weak ref
 100     */
 101     WeakReferenceHelper & SAL_CALL operator = ( const WeakReferenceHelper & rWeakRef );
 102
 103 #if defined LIBO_INTERNAL_ONLY
 104     WeakReferenceHelper & operator =(WeakReferenceHelper && other);
 105 #endif
 106
 107     /** Releases this reference and takes over hard reference xInt.
 108         If the implementation behind xInt does not support XWeak
 109         or XInt is null, then this reference is null.
 110
 111         @param xInt another hard reference
 112     */
 113     WeakReferenceHelper & SAL_CALL operator = (
 114             const css::uno::Reference< css::uno::XInterface > & xInt );
 115
 116 #if defined LIBO_INTERNAL_ONLY
 117     /** Releases this reference and takes over hard reference xWeak. This
 118          is faster than the XInterface constructor because we can skip doing an
 119          UNO_QUERY.
 120
 121         @param xWeak another hard reference
 122     */
 123     WeakReferenceHelper & operator = (
 124             const css::uno::Reference< css::uno::XWeak > & xWeak );
 125 #endif
 126
 127     /** Returns true if both weak refs reference to the same object.
 128
 129         @param rObj another weak ref
 130         @return true, if both weak refs reference to the same object.
 131     */
 132     bool SAL_CALL operator == ( const WeakReferenceHelper & rObj ) const
 133         { return (get() == rObj.get()); }
 134
 135     /**  Gets a hard reference to the object.
 136
 137          @return hard reference or null, if the weakly referenced interface has gone
 138     */
 139     css::uno::Reference< css::uno::XInterface > SAL_CALL get() const;
 140
 141     /**  Gets a hard reference to the object.
 142
 143          @return hard reference or null, if the weakly referenced interface has gone
 144     */
 145     SAL_CALL operator Reference< XInterface > () const
 146         { return get(); }
 147
 148     /** Releases this reference.
 149
 150         @since UDK 3.2.12
 151     */
 152     void SAL_CALL clear();
 153
 154 protected:
 155     /// @cond INTERNAL
 156     OWeakRefListener * m_pImpl;
 157     /// @endcond
 158 };
 159
 160 /** The WeakReference<> holds a weak reference to an object.
 161
 162     That object must implement the css::uno::XWeak interface.
 163
 164     The WeakReference itself is *not* thread safe, just as
 165     Reference itself isn't, but the implementation of the listeners etc.
 166     behind it *is* thread-safe, so multiple threads can have their own
 167     WeakReferences to the same XWeak object.
 168
 169     @tparam interface_type type of interface
 170 */
 171 template< class interface_type >
 172 class SAL_WARN_UNUSED WeakReference : public WeakReferenceHelper
 173 {
 174 public:
 175     /** Default ctor.  Creates an empty weak reference.
 176     */
 177     WeakReference()
 178         : WeakReferenceHelper()
 179         {}
 180
 181     /** Copy ctor.  Initialize this reference with a hard reference.
 182
 183         @param rRef another hard ref
 184     */
 185     WeakReference( const Reference< interface_type > & rRef )
 186         : WeakReferenceHelper( rRef )
 187         {}
 188
 189     /** Releases this reference and takes over hard reference xInt.
 190         If the implementation behind xInt does not support XWeak
 191         or XInt is null, then this reference is null.
 192
 193         @param xInt another hard reference
 194
 195         @since UDK 3.2.12
 196     */
 197     WeakReference & SAL_CALL operator = (
 198             const css::uno::Reference< interface_type > & xInt )
 199         { WeakReferenceHelper::operator=(xInt); return *this; }
 200
 201 #if defined LIBO_INTERNAL_ONLY
 202     /** Releases this reference and takes over hard reference xWeak. This
 203          is faster than the XInterface constructor because we can skip doing an
 204          UNO_QUERY.
 205
 206         @param xWeak another hard reference
 207     */
 208     WeakReference & operator = (
 209             const css::uno::Reference< css::uno::XWeak > & xWeak )
 210         { WeakReferenceHelper::operator=(xWeak); return *this; }
 211 #endif
 212
 213     /**  Gets a hard reference to the object.
 214
 215          @return hard reference or null, if the weakly referenced interface has gone
 216     */
 217     SAL_CALL operator Reference< interface_type > () const
 218         { return Reference< interface_type >::query( get() ); }
 219 };
 220
 221 }
 222 }
 223 }
 224 }
 225
 226 #endif
 227
 228 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */