Fixed doc typo
[libcds.git] / cds / intrusive / striped_set / adapter.h
index ec1cfa4828176b7dd1dfd02f9a3e681c7d8d8667..aa0bab6676bbcab5c01dbe21beaf10c768f1451d 100644 (file)
@@ -1,26 +1,52 @@
-//$$CDS-header$$
-
-#ifndef __CDS_INTRUSIVE_STRIPED_SET_ADAPTER_H
-#define __CDS_INTRUSIVE_STRIPED_SET_ADAPTER_H
+/*
+    This file is a part of libcds - Concurrent Data Structures library
+
+    (C) Copyright Maxim Khizhinsky (libcds.dev@gmail.com) 2006-2016
+
+    Source code repo: http://github.com/khizmax/libcds/
+    Download: http://sourceforge.net/projects/libcds/files/
+    
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this
+      list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.     
+*/
+
+#ifndef CDSLIB_INTRUSIVE_STRIPED_SET_ADAPTER_H
+#define CDSLIB_INTRUSIVE_STRIPED_SET_ADAPTER_H
 
 #include <cds/opt/options.h>
 #include <cds/intrusive/striped_set/resizing_policy.h>
 #include <cds/opt/hash.h>
 #include <cds/opt/compare.h>    // cds::opt::details::make_comparator - for some adapt specializations
-#include <cds/ref.h>
 
 namespace cds { namespace intrusive {
 
     /// StripedSet related definitions
     namespace striped_set {
-
         /// Default adapter for intrusive striped/refinable hash set
         /**
             By default, the metafunction does not make any transformation for container type \p Container.
             \p Container should provide interface suitable for the hash set.
 
-            The \p SetOptions template argument contains option pack
-            that has been passed to cds::intrusive::StripedSet.
+            The \p Options template argument contains option pack
+            that will be passed to \p cds::intrusive::StripedSet.
 
         <b>Bucket interface</b>
 
@@ -47,15 +73,14 @@ namespace cds { namespace intrusive {
                 \endcode
                 where \p item is the item inserted.
 
-                The user-defined functor \p f is called only if the inserting is success. It can be passed by reference
-                using <tt>boost::ref</tt>
+                The user-defined functor \p f is called only if the inserting is success.
                 <hr>
 
-            <b>Ensures that the \p item exists in the container</b>
-            \code template <typename Func> std::pair<bool, bool> ensure( value_type& val, Func f ) \endcode
+            <b>Updates the item in the container</b>
+            \code template <typename Func> std::pair<bool, bool> update( value_type& val, Func f, bool bAllowInsert = true ) \endcode
                 The operation performs inserting or changing data.
 
-                If the \p val key not found in the container, then \p val is inserted.
+                If the \p val key not found in the container, then \p val is inserted iff \p bAllowInsert is \p true.
                 Otherwise, the functor \p f is called with the item found.
 
                 The \p Func functor has the following interface:
@@ -72,16 +97,14 @@ namespace cds { namespace intrusive {
                 where arguments are:
                 - \p bNew - \p true if the item has been inserted, \p false otherwise
                 - \p item - container's item
-                - \p val - argument \p val passed into the \p ensure function
+                - \p val - argument \p val passed into the \p update() function
 
                 If \p val has been inserted (i.e. <tt>bNew == true</tt>) then \p item and \p val
                 are the same element: <tt>&item == &val</tt>. Otherwise, they are different.
 
                 The functor can change non-key fields of the \p item.
 
-                You can pass \p f argument by reference using <tt>boost::ref</tt>.
-
-                Returns <tt> std::pair<bool, bool> </tt> where \p first is true if operation is successfull,
+                Returns <tt> std::pair<bool, bool> </tt> where \p first is true if operation is successful,
                 \p second is true if new item has been added or \p false if the item with \p val key
                 already exists.
                 <hr>
@@ -102,7 +125,6 @@ namespace cds { namespace intrusive {
                     void operator()(value_type& val);
                 };
                 \endcode
-                The functor can be passed by reference using <tt>boost:ref</tt>
 
                 The type \p Q can differ from \ref value_type of items storing in the container.
                 Therefore, the \p value_type should be comparable with type \p Q.
@@ -125,8 +147,6 @@ namespace cds { namespace intrusive {
                 \endcode
                 where \p item is the item found, \p val is the <tt>find</tt> function argument.
 
-                You can pass \p f argument by reference using <tt>boost::ref</tt> or cds::ref.
-
                 The functor can change non-key fields of \p item.
                 The \p val argument may be non-const since it can be used as \p f functor destination i.e., the functor
                 can modify both arguments.
@@ -203,16 +223,9 @@ namespace cds { namespace intrusive {
                 typedef typename container_type::iterator       iterator        ;   ///< container iterator
                 typedef typename container_type::const_iterator const_iterator  ;   ///< container const iterator
 
-                typedef typename container_type::value_compare  key_comparator;
+                typedef typename container_type::key_compare  key_comparator;
 
             private:
-#       ifndef CDS_CXX11_LAMBDA_SUPPORT
-                struct empty_insert_functor {
-                    void operator()( value_type& )
-                    {}
-                };
-#       endif
-
                 container_type  m_Set;
 
             public:
@@ -229,21 +242,30 @@ namespace cds { namespace intrusive {
                 {
                     std::pair<iterator, bool> res = m_Set.insert( val );
                     if ( res.second )
-                        cds::unref(f)( val );
+                        f( val );
                     return res.second;
                 }
 
                 template <typename Func>
-                std::pair<bool, bool> ensure( value_type& val, Func f )
+                std::pair<bool, bool> update( value_type& val, Func f, bool bAllowInsert )
                 {
-                    std::pair<iterator, bool> res = m_Set.insert( val );
-                    cds::unref(f)( res.second, *res.first, val );
-                    return std::make_pair( true, res.second );
+                    if ( bAllowInsert ) {
+                        std::pair<iterator, bool> res = m_Set.insert( val );
+                        f( res.second, *res.first, val );
+                        return std::make_pair( true, res.second );
+                    }
+                    else {
+                        auto it = m_Set.find( val, key_comparator() );
+                        if ( it == m_Set.end() )
+                            return std::make_pair( false, false );
+                        f( false, *it, val );
+                        return std::make_pair( true, false );
+                    }
                 }
 
                 bool unlink( value_type& val )
                 {
-                    iterator it = m_Set.find( value_type(val) );
+                    iterator it = m_Set.find( val, key_comparator() );
                     if ( it == m_Set.end() || &(*it) != &val )
                         return false;
                     m_Set.erase( it );
@@ -257,7 +279,7 @@ namespace cds { namespace intrusive {
                     if (it == m_Set.end())
                         return nullptr;
                     value_type& val = *it;
-                    cds::unref(f)( val );
+                    f( val );
                     m_Set.erase( it );
                     return &val;
                 }
@@ -269,24 +291,24 @@ namespace cds { namespace intrusive {
                     if (it == m_Set.end())
                         return nullptr;
                     value_type& val = *it;
-                    cds::unref(f)( val );
+                    f( val );
                     m_Set.erase( it );
                     return &val;
                 }
 
                 template <typename Q, typename Func>
-                bool find( Q& key, Func f )
+                bool find( Q const& key, Func f )
                 {
                     return find( key, key_comparator(), f );
                 }
 
                 template <typename Q, typename Compare, typename Func>
-                bool find( Q& key, Compare cmp, Func f )
+                bool find( Q const& key, Compare cmp, Func f )
                 {
                     iterator it = m_Set.find( key, cmp );
                     if ( it == m_Set.end() )
                         return false;
-                    cds::unref(f)( *it, key );
+                    f( *it, key );
                     return true;
                 }
 
@@ -315,11 +337,7 @@ namespace cds { namespace intrusive {
                 {
                     value_type& val = *itWhat;
                     from.base_container().erase( itWhat );
-#           ifdef CDS_CXX11_LAMBDA_SUPPORT
                     insert( val, []( value_type& ) {} );
-#           else
-                    insert( val, empty_insert_functor() );
-#           endif
                 }
             };
         }   // namespace details
@@ -328,44 +346,4 @@ namespace cds { namespace intrusive {
     } // namespace striped_set
 }} // namespace cds::intrusive
 
-//@cond
-#if defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS3    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS4    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS5    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS6    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS7    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS8    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS9    typename... BIOptions
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS10    typename... BIOptions
-
-#   define CDS_BOOST_INTRUSIVE_OPTIONS3    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS4    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS5    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS6    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS7    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS8    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS9    BIOptions...
-#   define CDS_BOOST_INTRUSIVE_OPTIONS10    BIOptions...
-#else
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS3    typename BIO1, typename BIO2, typename BIO3
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS4    CDS_BOOST_INTRUSIVE_DECL_OPTIONS3, typename BIO4
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS5    CDS_BOOST_INTRUSIVE_DECL_OPTIONS4, typename BIO5
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS6    CDS_BOOST_INTRUSIVE_DECL_OPTIONS5, typename BIO6
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS7    CDS_BOOST_INTRUSIVE_DECL_OPTIONS6, typename BIO7
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS8    CDS_BOOST_INTRUSIVE_DECL_OPTIONS7, typename BIO8
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS9    CDS_BOOST_INTRUSIVE_DECL_OPTIONS8, typename BIO9
-#   define CDS_BOOST_INTRUSIVE_DECL_OPTIONS10   CDS_BOOST_INTRUSIVE_DECL_OPTIONS9, typename BIO10
-
-#   define CDS_BOOST_INTRUSIVE_OPTIONS3    BIO1,BIO2,BIO3
-#   define CDS_BOOST_INTRUSIVE_OPTIONS4    CDS_BOOST_INTRUSIVE_OPTIONS3, BIO4
-#   define CDS_BOOST_INTRUSIVE_OPTIONS5    CDS_BOOST_INTRUSIVE_OPTIONS4, BIO5
-#   define CDS_BOOST_INTRUSIVE_OPTIONS6    CDS_BOOST_INTRUSIVE_OPTIONS5, BIO6
-#   define CDS_BOOST_INTRUSIVE_OPTIONS7    CDS_BOOST_INTRUSIVE_OPTIONS6, BIO7
-#   define CDS_BOOST_INTRUSIVE_OPTIONS8    CDS_BOOST_INTRUSIVE_OPTIONS7, BIO8
-#   define CDS_BOOST_INTRUSIVE_OPTIONS9    CDS_BOOST_INTRUSIVE_OPTIONS8, BIO9
-#   define CDS_BOOST_INTRUSIVE_OPTIONS10   CDS_BOOST_INTRUSIVE_OPTIONS9, BIO10
-#endif
-//@endcond
-
-#endif // #ifndef __CDS_INTRUSIVE_STRIPED_SET_ADAPTER_H
+#endif // #ifndef CDSLIB_INTRUSIVE_STRIPED_SET_ADAPTER_H