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 #ifndef INCLUDED_CPPUHELPER_WEAKREF_HXX
  20 #define INCLUDED_CPPUHELPER_WEAKREF_HXX
  21
  22 #include "sal/config.h"
  23
  24 #include <cstddef>
  25
  26 #include "com/sun/star/uno/Reference.hxx"
  27 #include "com/sun/star/uno/XInterface.hpp"
  28 #include "cppuhelper/cppuhelperdllapi.h"
  29
  30
  31 namespace com
  32 {
  33 namespace sun
  34 {
  35 namespace star
  36 {
  37 namespace uno
  38 {
  39
  40 class OWeakRefListener;
  41
  42 /** The WeakReferenceHelper holds a weak reference to an object.
  43
  44     That object must implement the css::uno::XWeak interface.
  45
  46     The WeakReferenceHelper itself is *not* thread safe, just as
  47     Reference itself isn't, but the implementation of the listeners etc.
  48     behind it *is* thread-safe, so multiple threads can have their own
  49     WeakReferences to the same XWeak object.
  50 */
  51 class CPPUHELPER_DLLPUBLIC WeakReferenceHelper
  52 {
  53 public:
  54     /** Default ctor.  Creates an empty weak reference.
  55     */
  56     WeakReferenceHelper()
  57         : m_pImpl( NULL )
  58         {}
  59
  60     /** Copy ctor.  Initialize this reference with the same interface as in rWeakRef.
  61
  62         @param rWeakRef another weak ref
  63     */
  64     WeakReferenceHelper( const WeakReferenceHelper & rWeakRef );
  65
  66 #if defined LIBO_INTERNAL_ONLY
  67     WeakReferenceHelper(WeakReferenceHelper && other): m_pImpl(other.m_pImpl)
  68     { other.m_pImpl = nullptr; }
  69 #endif
  70
  71     /** Initialize this reference with the hard interface reference xInt. If the implementation
  72         behind xInt does not support XWeak or xInt is null then this reference will be null.
  73
  74         @param xInt another hard interface reference
  75     */
  76     WeakReferenceHelper( const css::uno::Reference< css::uno::XInterface > & xInt );
  77
  78     /** Releases this reference.
  79     */
  80     ~WeakReferenceHelper();
  81
  82     /** Releases this reference and takes over rWeakRef.
  83
  84         @param rWeakRef another weak ref
  85     */
  86     WeakReferenceHelper & SAL_CALL operator = ( const WeakReferenceHelper & rWeakRef );
  87
  88 #if defined LIBO_INTERNAL_ONLY
  89     WeakReferenceHelper & SAL_CALL operator =(WeakReferenceHelper && other);
  90 #endif
  91
  92     /** Releases this reference and takes over hard reference xInt.
  93         If the implementation behind xInt does not support XWeak
  94         or XInt is null, then this reference is null.
  95
  96         @param xInt another hard reference
  97     */
  98     WeakReferenceHelper & SAL_CALL operator = (
  99             const css::uno::Reference< css::uno::XInterface > & xInt );
 100
 101     /** Returns true if both weak refs reference to the same object.
 102
 103         @param rObj another weak ref
 104         @return true, if both weak refs reference to the same object.
 105     */
 106     bool SAL_CALL operator == ( const WeakReferenceHelper & rObj ) const
 107         { return (get() == rObj.get()); }
 108
 109     /**  Gets a hard reference to the object.
 110
 111          @return hard reference or null, if the weakly referenced interface has gone
 112     */
 113     css::uno::Reference< css::uno::XInterface > SAL_CALL get() const;
 114
 115     /**  Gets a hard reference to the object.
 116
 117          @return hard reference or null, if the weakly referenced interface has gone
 118     */
 119     SAL_CALL operator Reference< XInterface > () const
 120         { return get(); }
 121
 122     /** Releases this reference.
 123
 124         @since UDK 3.2.12
 125     */
 126     void SAL_CALL clear();
 127
 128 protected:
 129     /// @cond INTERNAL
 130     OWeakRefListener * m_pImpl;
 131     /// @endcond
 132 };
 133
 134 /** The WeakReference<> holds a weak reference to an object.
 135
 136     That object must implement the css::uno::XWeak interface.
 137
 138     The WeakReference itself is *not* thread safe, just as
 139     Reference itself isn't, but the implementation of the listeners etc.
 140     behind it *is* thread-safe, so multiple threads can have their own
 141     WeakReferences to the same XWeak object.
 142
 143     @tparam interface_type type of interface
 144 */
 145 template< class interface_type >
 146 class SAL_WARN_UNUSED WeakReference : public WeakReferenceHelper
 147 {
 148 public:
 149     /** Default ctor.  Creates an empty weak reference.
 150     */
 151     WeakReference()
 152         : WeakReferenceHelper()
 153         {}
 154
 155     /** Copy ctor.  Initialize this reference with a hard reference.
 156
 157         @param rRef another hard ref
 158     */
 159     WeakReference( const Reference< interface_type > & rRef )
 160         : WeakReferenceHelper( rRef )
 161         {}
 162
 163     /** Releases this reference and takes over hard reference xInt.
 164         If the implementation behind xInt does not support XWeak
 165         or XInt is null, then this reference is null.
 166
 167         @param xInt another hard reference
 168
 169         @since UDK 3.2.12
 170     */
 171     WeakReference & SAL_CALL operator = (
 172             const css::uno::Reference< interface_type > & xInt )
 173         { WeakReferenceHelper::operator=(xInt); return *this; }
 174
 175     /**  Gets a hard reference to the object.
 176
 177          @return hard reference or null, if the weakly referenced interface has gone
 178     */
 179     SAL_CALL operator Reference< interface_type > () const
 180         { return Reference< interface_type >::query( get() ); }
 181 };
 182
 183 }
 184 }
 185 }
 186 }
 187
 188 #endif
 189
 190 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */