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 #include <cstddef>
  27 #include <functional>
  28 #ifdef LIBO_INTERNAL_ONLY
  29 #include <type_traits>
  30 #endif
  31
  32 #include "sal/types.h"
  33
  34 namespace rtl
  35 {
  36
  37 /** Template reference class for reference type.
  38 */
  39 template <class reference_type>
  40 class Reference
  41 {
  42     /** The <b>reference_type</b> body pointer.
  43      */
  44     reference_type * m_pBody;
  45
  46
  47 public:
  48     /** Constructor...
  49      */
  50     Reference()
  51         : m_pBody (NULL)
  52     {}
  53
  54
  55     /** Constructor...
  56      */
  57     Reference (reference_type * pBody, __sal_NoAcquire)
  58         : m_pBody (pBody)
  59     {
  60     }
  61
  62     /** Constructor...
  63      */
  64     Reference (reference_type * pBody)
  65         : m_pBody (pBody)
  66     {
  67         if (m_pBody)
  68             m_pBody->acquire();
  69     }
  70
  71     /** Copy constructor...
  72      */
  73     Reference (const Reference<reference_type> & handle)
  74         : m_pBody (handle.m_pBody)
  75     {
  76         if (m_pBody)
  77             m_pBody->acquire();
  78     }
  79
  80 #ifdef LIBO_INTERNAL_ONLY
  81     /** Move constructor...
  82      */
  83     Reference (Reference<reference_type> && handle) noexcept
  84         : m_pBody (handle.m_pBody)
  85     {
  86         handle.m_pBody = nullptr;
  87     }
  88 #endif
  89
  90 #if defined LIBO_INTERNAL_ONLY
  91     /** Up-casting conversion constructor: Copies interface reference.
  92
  93         Does not work for up-casts to ambiguous bases.
  94
  95         @param rRef another reference
  96     */
  97     template< class derived_type >
  98     inline Reference(
  99         const Reference< derived_type > & rRef,
 100         std::enable_if_t<std::is_base_of_v<reference_type, derived_type>, int> = 0 )
 101         : m_pBody (rRef.get())
 102     {
 103         if (m_pBody)
 104             m_pBody->acquire();
 105     }
 106 #endif
 107
 108     /** Destructor...
 109      */
 110     ~Reference() COVERITY_NOEXCEPT_FALSE
 111     {
 112         if (m_pBody)
 113             m_pBody->release();
 114     }
 115
 116     /** Set...
 117          Similar to assignment.
 118      */
 119     Reference<reference_type> &
 120     SAL_CALL set (reference_type * pBody)
 121     {
 122         if (pBody)
 123             pBody->acquire();
 124         reference_type * const pOld = m_pBody;
 125         m_pBody = pBody;
 126         if (pOld)
 127             pOld->release();
 128         return *this;
 129     }
 130
 131     /** Assignment.
 132          Unbinds this instance from its body (if bound) and
 133          bind it to the body represented by the handle.
 134      */
 135     Reference<reference_type> &
 136     SAL_CALL operator= (const Reference<reference_type> & handle)
 137     {
 138         return set( handle.m_pBody );
 139     }
 140
 141 #ifdef LIBO_INTERNAL_ONLY
 142     /** Assignment.
 143      *   Unbinds this instance from its body (if bound),
 144      *   bind it to the body represented by the handle, and
 145      *   set the body represented by the handle to nullptr.
 146      */
 147     Reference<reference_type> &
 148     operator= (Reference<reference_type> && handle)
 149     {
 150         // self-movement guts ourself
 151         if (m_pBody)
 152             m_pBody->release();
 153         m_pBody = handle.m_pBody;
 154         handle.m_pBody = nullptr;
 155         return *this;
 156     }
 157 #endif
 158
 159     /** Assignment...
 160      */
 161     Reference<reference_type> &
 162     SAL_CALL operator= (reference_type * pBody)
 163     {
 164         return set( pBody );
 165     }
 166
 167     /** Unbind the body from this handle.
 168          Note that for a handle representing a large body,
 169          "handle.clear().set(new body());" _might_
 170          perform a little bit better than "handle.set(new body());",
 171          since in the second case two large objects exist in memory
 172          (the old body and the new body).
 173      */
 174     Reference<reference_type> & SAL_CALL clear()
 175     {
 176         if (m_pBody)
 177         {
 178             reference_type * const pOld = m_pBody;
 179             m_pBody = NULL;
 180             pOld->release();
 181         }
 182         return *this;
 183     }
 184
 185
 186     /** Get the body. Can be used instead of operator->().
 187          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 188          are the same.
 189      */
 190     reference_type * SAL_CALL get() const
 191     {
 192         return m_pBody;
 193     }
 194
 195
 196     /** Probably most common used: handle->someBodyOp().
 197      */
 198     reference_type * SAL_CALL operator->() const
 199     {
 200         assert(m_pBody != NULL);
 201         return m_pBody;
 202     }
 203
 204
 205     /** Allows (*handle).someBodyOp().
 206     */
 207     reference_type & SAL_CALL operator*() const
 208     {
 209         assert(m_pBody != NULL);
 210         return *m_pBody;
 211     }
 212
 213
 214     /** Returns True if the handle does point to a valid body.
 215      */
 216     bool SAL_CALL is() const
 217     {
 218         return (m_pBody != NULL);
 219     }
 220
 221 #if defined LIBO_INTERNAL_ONLY
 222     /** Returns True if the handle does point to a valid body.
 223      */
 224     explicit operator bool() const
 225     {
 226         return is();
 227     }
 228 #endif
 229
 230     /** Returns True if this points to pBody.
 231      */
 232     bool SAL_CALL operator== (const reference_type * pBody) const
 233     {
 234         return (m_pBody == pBody);
 235     }
 236
 237
 238     /** Returns True if handle points to the same body.
 239      */
 240     bool
 241     SAL_CALL operator== (const Reference<reference_type> & handle) const
 242     {
 243         return (m_pBody == handle.m_pBody);
 244     }
 245
 246
 247     /** Needed to place References into STL collection.
 248      */
 249     bool
 250     SAL_CALL operator!= (const Reference<reference_type> & handle) const
 251     {
 252         return (m_pBody != handle.m_pBody);
 253     }
 254
 255
 256     /** Needed to place References into STL collection.
 257      */
 258     bool
 259     SAL_CALL operator< (const Reference<reference_type> & handle) const
 260     {
 261         return (m_pBody < handle.m_pBody);
 262     }
 263
 264
 265     /** Needed to place References into STL collection.
 266      */
 267     bool
 268     SAL_CALL operator> (const Reference<reference_type> & handle) const
 269     {
 270         return (m_pBody > handle.m_pBody);
 271     }
 272 };
 273
 274 } // namespace rtl
 275
 276 #if defined LIBO_INTERNAL_ONLY
 277 namespace std
 278 {
 279
 280 /// @cond INTERNAL
 281 /**
 282   Make rtl::Reference hashable by default for use in STL containers.
 283
 284   @since LibreOffice 6.3
 285 */
 286 template<typename T>
 287 struct hash<::rtl::Reference<T>>
 288 {
 289     std::size_t operator()(::rtl::Reference<T> const & s) const
 290     { return std::size_t(s.get()); }
 291 };
 292 /// @endcond
 293
 294 }
 295
 296 #endif
 297
 298 #endif /* ! INCLUDED_RTL_REF_HXX */
 299
 300 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */