LCOV - code coverage report
Current view: top level - include/o3tl - cow_wrapper.hxx (source / functions) Hit Total Coverage
Test: commit c8344322a7af75b84dd3ca8f78b05543a976dfd5 Lines: 64 64 100.0 %
Date: 2015-06-13 12:38:46 Functions: 426 465 91.6 %
Legend: Lines: hit not hit

          Line data    Source code
       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_O3TL_COW_WRAPPER_HXX
      21             : #define INCLUDED_O3TL_COW_WRAPPER_HXX
      22             : 
      23             : #include <osl/interlck.h>
      24             : 
      25             : #include <algorithm>
      26             : 
      27             : #include <boost/utility.hpp>
      28             : #include <boost/checked_delete.hpp>
      29             : 
      30             : namespace o3tl
      31             : {
      32             :     /** Thread-unsafe refcounting
      33             : 
      34             :         This is the default locking policy for cow_wrapper. No
      35             :         locking/guarding against concurrent access is performed
      36             :         whatsoever.
      37             :      */
      38             :     struct UnsafeRefCountingPolicy
      39             :     {
      40             :         typedef sal_uInt32 ref_count_t;
      41    39193188 :         static void incrementCount( ref_count_t& rCount ) { ++rCount; }
      42    51856204 :         static bool decrementCount( ref_count_t& rCount ) { return --rCount != 0; }
      43             :     };
      44             : 
      45             :     /** Thread-safe refcounting
      46             : 
      47             :         Use this to have the cow_wrapper refcounting mechanisms employ
      48             :         the thread-safe oslInterlockedCount .
      49             :      */
      50             :     struct ThreadSafeRefCountingPolicy
      51             :     {
      52             :         typedef oslInterlockedCount ref_count_t;
      53      270276 :         static void incrementCount( ref_count_t& rCount ) { osl_atomic_increment(&rCount); }
      54      379778 :         static bool decrementCount( ref_count_t& rCount )
      55             :         {
      56      379778 :             if( rCount == 1 ) // caller is already the only/last reference
      57      109502 :                 return false;
      58             :             else
      59      270276 :                 return osl_atomic_decrement(&rCount) != 0;
      60             :         }
      61             :     };
      62             : 
      63             :     /** Copy-on-write wrapper.
      64             : 
      65             :         This template provides copy-on-write semantics for the wrapped
      66             :         type: when copying, the operation is performed shallow,
      67             :         i.e. different cow_wrapper objects share the same underlying
      68             :         instance. Only when accessing the underlying object via
      69             :         non-const methods, a unique copy is provided.
      70             : 
      71             :         The type parameter <code>T</code> must satisfy the following
      72             :         requirements: it must be default-constructible, copyable (it
      73             :         need not be assignable), and be of non-reference type. Note
      74             :         that, despite the fact that this template provides access to
      75             :         the wrapped type via pointer-like methods
      76             :         (<code>operator->()</code> and <code>operator*()</code>), it does
      77             :         <em>not</em> work like e.g. the std smart pointer wrappers
      78             :         (shared_ptr, unique_ptr, etc.). Internally, the cow_wrapper
      79             :         holds a by-value instance of the wrapped object. This is to
      80             :         avoid one additional heap allocation, and providing access via
      81             :         <code>operator->()</code>/<code>operator*()</code> is because
      82             :         <code>operator.()</code> cannot be overridden.
      83             : 
      84             :         Regarding thread safety: this wrapper is <em>not</em>
      85             :         thread-safe per se, because cow_wrapper has no way of
      86             :         synchronizing the potentially many different cow_wrapper
      87             :         instances, that reference a single shared value_type
      88             :         instance. That said, when passing
      89             :         <code>ThreadSafeRefCountingPolicy</code> as the
      90             :         <code>MTPolicy</code> parameter, accessing a thread-safe
      91             :         pointee through multiple cow_wrapper instances might be
      92             :         thread-safe, if the individual pointee methods are
      93             :         thread-safe, <em>including</em> pointee's copy
      94             :         constructor. Any wrapped object that needs external
      95             :         synchronisation (e.g. via an external mutex, which arbitrates
      96             :         access to object methods, and can be held across multiple
      97             :         object method calls) cannot easily be dealt with in a
      98             :         thread-safe way, because, as noted, objects are shared behind
      99             :         the client's back.
     100             : 
     101             :         @attention if one wants to use the pimpl idiom together with
     102             :         cow_wrapper (i.e. put an opaque type into the cow_wrapper),
     103             :         then <em>all<em> methods in the surrounding class needs to be
     104             :         non-inline (<em>including</em> destructor, copy constructor
     105             :         and assignment operator).
     106             : 
     107             :         @example
     108             :         <pre>
     109             : class cow_wrapper_client_impl;
     110             : 
     111             : class cow_wrapper_client
     112             : {
     113             : public:
     114             :     cow_wrapper_client();
     115             :     cow_wrapper_client( const cow_wrapper_client& );
     116             :     ~cow_wrapper_client();
     117             : 
     118             :     cow_wrapper_client& operator=( const cow_wrapper_client& );
     119             : 
     120             :     void modify( int nVal );
     121             :     int queryUnmodified() const;
     122             : 
     123             : private:
     124             :     otl::cow_wrapper< cow_wrapper_client_impl > maImpl;
     125             : };
     126             :         </pre>
     127             :         and the implementation file would look like this:
     128             :         <pre>
     129             : class cow_wrapper_client_impl
     130             : {
     131             : public:
     132             :     void setValue( int nVal ) { mnValue = nVal; }
     133             :     int getValue() const { return mnValue; }
     134             : 
     135             : private:
     136             :     int mnValue;
     137             : }
     138             : 
     139             : cow_wrapper_client::cow_wrapper_client() :
     140             :     maImpl()
     141             : {
     142             : }
     143             : cow_wrapper_client::cow_wrapper_client( const cow_wrapper_client& rSrc ) :
     144             :     maImpl( rSrc.maImpl )
     145             : {
     146             : }
     147             : cow_wrapper_client::~cow_wrapper_client()
     148             : {
     149             : }
     150             : cow_wrapper_client& cow_wrapper_client::operator=( const cow_wrapper_client& rSrc )
     151             : {
     152             :     maImpl = rSrc.maImpl;
     153             :     return *this;
     154             : }
     155             : void cow_wrapper_client::modify( int nVal )
     156             : {
     157             :     maImpl->setValue( nVal );
     158             : }
     159             : int cow_wrapper_client::queryUnmodified() const
     160             : {
     161             :     return maImpl->getValue();
     162             : }
     163             :         </pre>
     164             :      */
     165             :     template<typename T, class MTPolicy=UnsafeRefCountingPolicy> class cow_wrapper
     166             :     {
     167             :         /** shared value object - gets cloned before cow_wrapper hands
     168             :             out a non-const reference to it
     169             :          */
     170    12777613 :         struct impl_t : private boost::noncopyable
     171             :         {
     172        3982 :             impl_t() :
     173             :                 m_value(),
     174        3982 :                 m_ref_count(1)
     175             :             {
     176        3982 :             }
     177             : 
     178    12787432 :             explicit impl_t( const T& v ) :
     179             :                 m_value(v),
     180    12787432 :                 m_ref_count(1)
     181             :             {
     182    12787432 :             }
     183             : 
     184             :             T                              m_value;
     185             :             typename MTPolicy::ref_count_t m_ref_count;
     186             :         };
     187             : 
     188    52235982 :         void release()
     189             :         {
     190    52235982 :             if( !MTPolicy::decrementCount(m_pimpl->m_ref_count) )
     191    12778262 :                 boost::checked_delete(m_pimpl), m_pimpl=0;
     192    52235982 :         }
     193             : 
     194             :     public:
     195             :         typedef T        value_type;
     196             :         typedef T*       pointer;
     197             :         typedef const T* const_pointer;
     198             :         typedef MTPolicy mt_policy;
     199             : 
     200             :         /** Default-construct wrapped type instance
     201             :          */
     202        3982 :         cow_wrapper() :
     203        3982 :             m_pimpl( new impl_t() )
     204             :         {
     205        3982 :         }
     206             : 
     207             :         /** Copy-construct wrapped type instance from given object
     208             :          */
     209     4295002 :         explicit cow_wrapper( const value_type& r ) :
     210     4295002 :             m_pimpl( new impl_t(r) )
     211             :         {
     212     4295002 :         }
     213             : 
     214             :         /** Shallow-copy given cow_wrapper
     215             :          */
     216    37735457 :         explicit cow_wrapper( const cow_wrapper& rSrc ) : // nothrow
     217    37735457 :             m_pimpl( rSrc.m_pimpl )
     218             :         {
     219    37735457 :             MTPolicy::incrementCount( m_pimpl->m_ref_count );
     220    37735457 :         }
     221             : 
     222    42015545 :         ~cow_wrapper() // nothrow, if ~T does not throw
     223             :         {
     224    42015545 :             release();
     225    42015545 :         }
     226             : 
     227             :         /// now sharing rSrc cow_wrapper instance with us
     228     1728007 :         cow_wrapper& operator=( const cow_wrapper& rSrc ) // nothrow
     229             :         {
     230             :             // this already guards against self-assignment
     231     1728007 :             MTPolicy::incrementCount( rSrc.m_pimpl->m_ref_count );
     232             : 
     233     1728007 :             release();
     234     1728007 :             m_pimpl = rSrc.m_pimpl;
     235             : 
     236     1728007 :             return *this;
     237             :         }
     238             : 
     239             :         /// unshare with any other cow_wrapper instance
     240    49762735 :         value_type& make_unique()
     241             :         {
     242    49762735 :             if( m_pimpl->m_ref_count > 1 )
     243             :             {
     244     8492430 :                 impl_t* pimpl = new impl_t(m_pimpl->m_value);
     245     8492430 :                 release();
     246     8492430 :                 m_pimpl = pimpl;
     247             :             }
     248             : 
     249    49762735 :             return m_pimpl->m_value;
     250             :         }
     251             : 
     252             :         /// true, if not shared with any other cow_wrapper instance
     253          15 :         bool is_unique() const // nothrow
     254             :         {
     255          15 :             return m_pimpl->m_ref_count == 1;
     256             :         }
     257             : 
     258             :         /// return number of shared instances (1 for unique object)
     259          27 :         typename MTPolicy::ref_count_t use_count() const // nothrow
     260             :         {
     261          27 :             return m_pimpl->m_ref_count;
     262             :         }
     263             : 
     264           3 :         void swap(cow_wrapper& r) // never throws
     265             :         {
     266           3 :             std::swap(m_pimpl, r.m_pimpl);
     267           3 :         }
     268             : 
     269    49686236 :         pointer           operator->()       { return &make_unique(); }
     270       76284 :         value_type&       operator*()        { return make_unique(); }
     271   288660361 :         const_pointer     operator->() const { return &m_pimpl->m_value; }
     272     1235888 :         const value_type& operator*()  const { return m_pimpl->m_value; }
     273             : 
     274             :         pointer           get()       { return &make_unique(); }
     275             :         const_pointer     get() const { return &m_pimpl->m_value; }
     276             : 
     277             :         /// true, if both cow_wrapper internally share the same object
     278     6614695 :         bool              same_object( const cow_wrapper& rOther ) const
     279             :         {
     280     6614695 :             return rOther.m_pimpl == m_pimpl;
     281             :         }
     282             : 
     283             :     private:
     284             :         impl_t* m_pimpl;
     285             :     };
     286             : 
     287             : 
     288      435084 :     template<class T, class P> inline bool operator==( const cow_wrapper<T,P>& a,
     289             :                                                        const cow_wrapper<T,P>& b )
     290             :     {
     291      435084 :         return a.same_object(b) || *a == *b;
     292             :     }
     293             : 
     294           9 :     template<class T, class P> inline bool operator!=( const cow_wrapper<T,P>& a,
     295             :                                                        const cow_wrapper<T,P>& b )
     296             :     {
     297           9 :         return !a.same_object(b) && *a != *b;
     298             :     }
     299             : 
     300           6 :     template<class A, class B, class P> inline bool operator<( const cow_wrapper<A,P>& a,
     301             :                                                                const cow_wrapper<B,P>& b )
     302             :     {
     303           6 :         return *a < *b;
     304             :     }
     305             : 
     306           3 :     template<class T, class P> inline void swap( cow_wrapper<T,P>& a,
     307             :                                                  cow_wrapper<T,P>& b )
     308             :     {
     309           3 :         a.swap(b);
     310           3 :     }
     311             : 
     312             :     // to enable boost::mem_fn on cow_wrapper
     313             :     template<class T, class P> inline T * get_pointer( const cow_wrapper<T,P>& r )
     314             :     {
     315             :         return r.get();
     316             :     }
     317             : 
     318             : }
     319             : 
     320             : #endif /* INCLUDED_O3TL_COW_WRAPPER_HXX */
     321             : 
     322             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.11