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