sal/inc/rtl/ref.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ref.hxx,v $
  10  * $Revision: 1.8 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_REF_HXX_
  32 #define _RTL_REF_HXX_
  33
  34 #include <sal/types.h>
  35 #include <osl/diagnose.h>
  36 #include <osl/interlck.h>
  37
  38 namespace rtl
  39 {
  40
  41 /** Interface for a reference type.
  42 */
  43 class IReference
  44 {
  45 public:
  46     /** @see osl_incrementInterlockedCount.
  47      */
  48     virtual oslInterlockedCount SAL_CALL acquire() = 0;
  49
  50     /** @see osl_decrementInterlockedCount.
  51      */
  52     virtual oslInterlockedCount SAL_CALL release() = 0;
  53 };
  54
  55
  56 /** Template reference class for reference type derived from IReference.
  57 */
  58 template <class reference_type>
  59 class Reference
  60 {
  61     /** The <b>reference_type</b> body pointer.
  62      */
  63     reference_type * m_pBody;
  64
  65
  66 public:
  67     /** Constructor...
  68      */
  69     inline Reference()
  70         : m_pBody (0)
  71     {}
  72
  73
  74     /** Constructor...
  75      */
  76     inline Reference (reference_type * pBody)
  77         : m_pBody (pBody)
  78     {
  79         if (m_pBody)
  80             m_pBody->acquire();
  81     }
  82
  83
  84     /** Copy constructor...
  85      */
  86     inline Reference (const Reference<reference_type> & handle)
  87         : m_pBody (handle.m_pBody)
  88     {
  89         if (m_pBody)
  90             m_pBody->acquire();
  91     }
  92
  93
  94     /** Destructor...
  95      */
  96     inline ~Reference()
  97     {
  98         if (m_pBody)
  99             m_pBody->release();
 100     }
 101
 102     /** Set...
 103          Similar to assignment.
 104      */
 105     inline Reference<reference_type> &
 106     SAL_CALL set (reference_type * pBody)
 107     {
 108         if (pBody)
 109             pBody->acquire();
 110         reference_type * const pOld = m_pBody;
 111         m_pBody = pBody;
 112         if (pOld)
 113             pOld->release();
 114         return *this;
 115     }
 116
 117     /** Assignment.
 118          Unbinds this instance from its body (if bound) and
 119          bind it to the body represented by the handle.
 120      */
 121     inline Reference<reference_type> &
 122     SAL_CALL operator= (const Reference<reference_type> & handle)
 123     {
 124         return set( handle.m_pBody );
 125     }
 126
 127     /** Assignment...
 128      */
 129     inline Reference<reference_type> &
 130     SAL_CALL operator= (reference_type * pBody)
 131     {
 132         return set( pBody );
 133     }
 134
 135     /** Unbind the body from this handle.
 136          Note that for a handle representing a large body,
 137          "handle.clear().set(new body());" _might_
 138          perform a little bit better than "handle.set(new body());",
 139          since in the second case two large objects exist in memory
 140          (the old body and the new body).
 141      */
 142     inline Reference<reference_type> & SAL_CALL clear()
 143     {
 144         if (m_pBody)
 145         {
 146             reference_type * const pOld = m_pBody;
 147             m_pBody = 0;
 148             pOld->release();
 149         }
 150         return *this;
 151     }
 152
 153
 154     /** Get the body. Can be used instead of operator->().
 155          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 156          are the same.
 157      */
 158     inline reference_type * SAL_CALL get() const
 159     {
 160         return m_pBody;
 161     }
 162
 163
 164     /** Probably most common used: handle->someBodyOp().
 165      */
 166     inline reference_type * SAL_CALL operator->() const
 167     {
 168         OSL_PRECOND(m_pBody, "Reference::operator->() : null body");
 169         return m_pBody;
 170     }
 171
 172
 173     /** Allows (*handle).someBodyOp().
 174     */
 175     inline reference_type & SAL_CALL operator*() const
 176     {
 177         OSL_PRECOND(m_pBody, "Reference::operator*() : null body");
 178         return *m_pBody;
 179     }
 180
 181
 182     /** Returns True if the handle does point to a valid body.
 183      */
 184     inline sal_Bool SAL_CALL is() const
 185     {
 186         return (m_pBody != 0);
 187     }
 188
 189
 190     /** Returns True if this points to pBody.
 191      */
 192     inline sal_Bool SAL_CALL operator== (const reference_type * pBody) const
 193     {
 194         return (m_pBody == pBody);
 195     }
 196
 197
 198     /** Returns True if handle points to the same body.
 199      */
 200     inline sal_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 sal_Bool
 210     SAL_CALL operator!= (const Reference<reference_type> & handle) const
 211     {
 212         return (m_pBody != handle.m_pBody);
 213     }
 214
 215
 216     /** Needed to place References into STL collection.
 217      */
 218     inline sal_Bool
 219     SAL_CALL operator< (const Reference<reference_type> & handle) const
 220     {
 221         return (m_pBody < handle.m_pBody);
 222     }
 223
 224
 225     /** Needed to place References into STL collection.
 226      */
 227     inline sal_Bool
 228     SAL_CALL operator> (const Reference<reference_type> & handle) const
 229     {
 230         return (m_pBody > handle.m_pBody);
 231     }
 232 };
 233
 234 /** @internal
 235     Enables boost::mem_fn and boost::bind to recognize Reference.
 236 */
 237 template <typename T>
 238 inline T * get_pointer( Reference<T> const& r )
 239 {
 240     return r.get();
 241 }
 242
 243 } // namespace rtl
 244
 245 #endif /* !_RTL_REF_HXX_ */