include/rtl/ref.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 #ifndef INCLUDED_RTL_REF_HXX
  21 #define INCLUDED_RTL_REF_HXX
  22
  23 #include <sal/types.h>
  24 #include <osl/diagnose.h>
  25 #include <osl/interlck.h>
  26
  27 namespace rtl
  28 {
  29
  30 /** Interface for a reference type.
  31 */
  32 class IReference
  33 {
  34 public:
  35     /** @see osl_incrementInterlockedCount.
  36      */
  37     virtual oslInterlockedCount SAL_CALL acquire() = 0;
  38
  39     /** @see osl_decrementInterlockedCount.
  40      */
  41     virtual oslInterlockedCount SAL_CALL release() = 0;
  42
  43 #if !defined _MSC_VER // public -> protected changes mangled names there
  44 protected:
  45 #endif
  46     ~IReference() {}
  47         // avoid warnings about virtual members and non-virtual dtor
  48 };
  49
  50
  51 /** Template reference class for reference type derived from IReference.
  52 */
  53 template <class reference_type>
  54 class Reference
  55 {
  56     /** The <b>reference_type</b> body pointer.
  57      */
  58     reference_type * m_pBody;
  59
  60
  61 public:
  62     /** Constructor...
  63      */
  64     inline Reference()
  65         : m_pBody (0)
  66     {}
  67
  68
  69     /** Constructor...
  70      */
  71     inline Reference (reference_type * pBody)
  72         : m_pBody (pBody)
  73     {
  74         if (m_pBody)
  75             m_pBody->acquire();
  76     }
  77
  78
  79     /** Copy constructor...
  80      */
  81     inline Reference (const Reference<reference_type> & handle)
  82         : m_pBody (handle.m_pBody)
  83     {
  84         if (m_pBody)
  85             m_pBody->acquire();
  86     }
  87
  88
  89     /** Destructor...
  90      */
  91     inline ~Reference()
  92     {
  93         if (m_pBody)
  94             m_pBody->release();
  95     }
  96
  97     /** Set...
  98          Similar to assignment.
  99      */
 100     inline Reference<reference_type> &
 101     SAL_CALL set (reference_type * pBody)
 102     {
 103         if (pBody)
 104             pBody->acquire();
 105         reference_type * const pOld = m_pBody;
 106         m_pBody = pBody;
 107         if (pOld)
 108             pOld->release();
 109         return *this;
 110     }
 111
 112     /** Assignment.
 113          Unbinds this instance from its body (if bound) and
 114          bind it to the body represented by the handle.
 115      */
 116     inline Reference<reference_type> &
 117     SAL_CALL operator= (const Reference<reference_type> & handle)
 118     {
 119         return set( handle.m_pBody );
 120     }
 121
 122     /** Assignment...
 123      */
 124     inline Reference<reference_type> &
 125     SAL_CALL operator= (reference_type * pBody)
 126     {
 127         return set( pBody );
 128     }
 129
 130     /** Unbind the body from this handle.
 131          Note that for a handle representing a large body,
 132          "handle.clear().set(new body());" _might_
 133          perform a little bit better than "handle.set(new body());",
 134          since in the second case two large objects exist in memory
 135          (the old body and the new body).
 136      */
 137     inline Reference<reference_type> & SAL_CALL clear()
 138     {
 139         if (m_pBody)
 140         {
 141             reference_type * const pOld = m_pBody;
 142             m_pBody = 0;
 143             pOld->release();
 144         }
 145         return *this;
 146     }
 147
 148
 149     /** Get the body. Can be used instead of operator->().
 150          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 151          are the same.
 152      */
 153     inline reference_type * SAL_CALL get() const
 154     {
 155         return m_pBody;
 156     }
 157
 158
 159     /** Probably most common used: handle->someBodyOp().
 160      */
 161     inline reference_type * SAL_CALL operator->() const
 162     {
 163         OSL_PRECOND(m_pBody, "Reference::operator->() : null body");
 164         return m_pBody;
 165     }
 166
 167
 168     /** Allows (*handle).someBodyOp().
 169     */
 170     inline reference_type & SAL_CALL operator*() const
 171     {
 172         OSL_PRECOND(m_pBody, "Reference::operator*() : null body");
 173         return *m_pBody;
 174     }
 175
 176
 177     /** Returns True if the handle does point to a valid body.
 178      */
 179     inline sal_Bool SAL_CALL is() const
 180     {
 181         return (m_pBody != 0);
 182     }
 183
 184
 185     /** Returns True if this points to pBody.
 186      */
 187     inline sal_Bool SAL_CALL operator== (const reference_type * pBody) const
 188     {
 189         return (m_pBody == pBody);
 190     }
 191
 192
 193     /** Returns True if handle points to the same body.
 194      */
 195     inline sal_Bool
 196     SAL_CALL operator== (const Reference<reference_type> & handle) const
 197     {
 198         return (m_pBody == handle.m_pBody);
 199     }
 200
 201
 202     /** Needed to place References into STL collection.
 203      */
 204     inline sal_Bool
 205     SAL_CALL operator!= (const Reference<reference_type> & handle) const
 206     {
 207         return (m_pBody != handle.m_pBody);
 208     }
 209
 210
 211     /** Needed to place References into STL collection.
 212      */
 213     inline sal_Bool
 214     SAL_CALL operator< (const Reference<reference_type> & handle) const
 215     {
 216         return (m_pBody < handle.m_pBody);
 217     }
 218
 219
 220     /** Needed to place References into STL collection.
 221      */
 222     inline sal_Bool
 223     SAL_CALL operator> (const Reference<reference_type> & handle) const
 224     {
 225         return (m_pBody > handle.m_pBody);
 226     }
 227 };
 228
 229 /// @cond INTERNAL
 230 /** Enables boost::mem_fn and boost::bind to recognize Reference.
 231 */
 232 template <typename T>
 233 inline T * get_pointer( Reference<T> const& r )
 234 {
 235     return r.get();
 236 }
 237 /// @endcond
 238
 239 } // namespace rtl
 240
 241 #endif /* ! INCLUDED_RTL_REF_HXX */
 242
 243 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */