Added copyright and license
[libcds.git] / cds / intrusive / split_list.h
index 8225b147bda0f08a2b451c25b8f2ed48976fc0ff..9a7e198e55a61d31bacc2671a1557cb0b22b074c 100644 (file)
@@ -1,8 +1,37 @@
-//$$CDS-header$$
-
-#ifndef __CDS_INTRUSIVE_SPLIT_LIST_H
-#define __CDS_INTRUSIVE_SPLIT_LIST_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_SPLIT_LIST_H
+#define CDSLIB_INTRUSIVE_SPLIT_LIST_H
+
+#include <limits>
 #include <cds/intrusive/details/split_list_base.h>
 
 namespace cds { namespace intrusive {
@@ -24,23 +53,23 @@ namespace cds { namespace intrusive {
         [from [2003] Ori Shalev, Nir Shavit "Split-Ordered Lists - Lock-free Resizable Hash Tables"]
 
         The algorithm keeps all the items in one lock-free linked list, and gradually assigns the bucket pointers to
-        the places in the list where a sublist of \93correct\94 items can be found. A bucket is initialized upon first
-        access by assigning it to a new \93dummy\94 node (dashed contour) in the list, preceding all items that should be
-        in that bucket. A newly created bucket splits an older bucket\92s chain, reducing the access cost to its items. The
-        table uses a modulo 2**i hash (there are known techniques for \93pre-hashing\94 before a modulo 2**i hash
+        the places in the list where a sublist of 'correct' items can be found. A bucket is initialized upon first
+        access by assigning it to a new 'dummy' node (dashed contour) in the list, preceding all items that should be
+        in that bucket. A newly created bucket splits an older bucket's chain, reducing the access cost to its items. The
+        table uses a modulo 2**i hash (there are known techniques for 'pre-hashing' before a modulo 2**i hash
         to overcome possible binary correlations among values). The table starts at size 2 and repeatedly doubles in size.
 
         Unlike moving an item, the operation of directing a bucket pointer can be done
-        in a single CAS operation, and since items are not moved, they are never \93lost\94.
+        in a single CAS operation, and since items are not moved, they are never 'lost'.
         However, to make this approach work, one must be able to keep the items in the
-        list sorted in such a way that any bucket\92s sublist can be \93split\94 by directing a new
+        list sorted in such a way that any bucket's sublist can be 'split' by directing a new
         bucket pointer within it. This operation must be recursively repeatable, as every
         split bucket may be split again and again as the hash table grows. To achieve this
         goal the authors introduced recursive split-ordering, a new ordering on keys that keeps items
         in a given bucket adjacent in the list throughout the repeated splitting process.
 
         Magically, yet perhaps not surprisingly, recursive split-ordering is achieved by
-        simple binary reversal: reversing the bits of the hash key so that the new key\92s
+        simple binary reversal: reversing the bits of the hash key so that the new key's
         most significant bits (MSB) are those that were originally its least significant.
         The split-order keys of regular nodes are exactly the bit-reverse image of the original
         keys after turning on their MSB. For example, items 9 and 13 are in the <tt>1 mod
@@ -49,7 +78,7 @@ namespace cds { namespace intrusive {
 
         To insert (respectively delete or search for) an item in the hash table, hash its
         key to the appropriate bucket using recursive split-ordering, follow the pointer to
-        the appropriate location in the sorted items list, and traverse the list until the key\92s
+        the appropriate location in the sorted items list, and traverse the list until the key's
         proper location in the split-ordering (respectively until the key or a key indicating
         the item is not in the list is found). Because of the combinatorial structure induced
         by the split-ordering, this will require traversal of no more than an expected constant number of items.
@@ -267,11 +296,11 @@ namespace cds { namespace intrusive {
             }
 
             template <typename Func>
-            std::pair<bool, bool> ensure_at( dummy_node_type * pHead, value_type& val, Func func )
+            std::pair<bool, bool> update_at( dummy_node_type * pHead, value_type& val, Func func, bool bAllowInsert )
             {
                 assert( pHead != nullptr );
                 bucket_head_type h(pHead);
-                return base_class::ensure_at( h, val, func );
+                return base_class::update_at( h, val, func, bAllowInsert );
             }
 
             bool unlink_at( dummy_node_type * pHead, value_type& val )
@@ -298,7 +327,7 @@ namespace cds { namespace intrusive {
             }
 
             template <typename Q, typename Compare>
-            bool extract_at( dummy_node_type * pHead, typename gc::Guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
+            bool extract_at( dummy_node_type * pHead, typename guarded_ptr::native_guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
             {
                 assert( pHead != nullptr );
                 bucket_head_type h(pHead);
@@ -322,7 +351,7 @@ namespace cds { namespace intrusive {
             }
 
             template <typename Q, typename Compare>
-            bool get_at( dummy_node_type * pHead, typename gc::Guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
+            bool get_at( dummy_node_type * pHead, typename guarded_ptr::native_guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
             {
                 assert( pHead != nullptr );
                 bucket_head_type h(pHead);
@@ -345,6 +374,7 @@ namespace cds { namespace intrusive {
         ordered_list_wrapper    m_List;             ///< Ordered list containing split-list items
         bucket_table            m_Buckets;          ///< bucket table
         atomics::atomic<size_t> m_nBucketCountLog2; ///< log2( current bucket count )
+        atomics::atomic<size_t> m_nMaxItemCount;    ///< number of items container can hold, before we have to resize
         item_counter            m_ItemCounter;      ///< Item counter
         hash                    m_HashFunctor;      ///< Hash functor
         stat                    m_Stat;             ///< Internal statistics
@@ -373,13 +403,13 @@ namespace cds { namespace intrusive {
 
         size_t bucket_no( size_t nHash ) const
         {
-            return nHash & ( (1 << m_nBucketCountLog2.load(atomics::memory_order_relaxed)) - 1 );
+            return nHash & ( (1 << m_nBucketCountLog2.load(memory_model::memory_order_relaxed)) - 1 );
         }
 
         static size_t parent_bucket( size_t nBucket )
         {
             assert( nBucket > 0 );
-            return nBucket & ~( 1 << bitop::MSBnz( nBucket ) );
+            return nBucket & ~( 1 << bitop::MSBnz( nBucket ));
         }
 
         dummy_node_type * init_bucket( size_t nBucket )
@@ -397,8 +427,8 @@ namespace cds { namespace intrusive {
 
             // Allocate a dummy node for new bucket
             {
-                dummy_node_type * pBucket = alloc_dummy_node( split_list::dummy_hash( nBucket ) );
-                if ( m_List.insert_aux_node( pParentBucket, pBucket ) ) {
+                dummy_node_type * pBucket = alloc_dummy_node( split_list::dummy_hash( nBucket ));
+                if ( m_List.insert_aux_node( pParentBucket, pBucket )) {
                     m_Buckets.bucket( nBucket, pBucket );
                     m_Stat.onNewBucket();
                     return pBucket;
@@ -411,7 +441,6 @@ namespace cds { namespace intrusive {
             // In this point, we must wait while nBucket is empty.
             // The compiler can decide that waiting loop can be "optimized" (stripped)
             // To prevent this situation, we use waiting on volatile bucket_head_ptr pointer.
-            //
             m_Stat.onBucketInitContenton();
             back_off bkoff;
             while ( true ) {
@@ -431,7 +460,7 @@ namespace cds { namespace intrusive {
             if ( pHead == nullptr )
                 pHead = init_bucket( nBucket );
 
-            assert( pHead->is_dummy() );
+            assert( pHead->is_dummy());
 
             return pHead;
         }
@@ -454,13 +483,31 @@ namespace cds { namespace intrusive {
             m_Buckets.bucket( 0, pNode );
         }
 
-        void    inc_item_count()
+        static size_t max_item_count( size_t nBucketCount, size_t nLoadFactor )
         {
-            size_t sz = m_nBucketCountLog2.load(atomics::memory_order_relaxed);
-            if ( ( ++m_ItemCounter >> sz ) > m_Buckets.load_factor() && ((size_t)(1 << sz )) < m_Buckets.capacity() )
-            {
-                m_nBucketCountLog2.compare_exchange_strong( sz, sz + 1, atomics::memory_order_seq_cst, atomics::memory_order_relaxed );
+            return nBucketCount * nLoadFactor;
+        }
+
+        void inc_item_count()
+        {
+            size_t nMaxCount = m_nMaxItemCount.load(memory_model::memory_order_relaxed);
+            if ( ++m_ItemCounter <= nMaxCount )
+                return;
+
+            size_t sz = m_nBucketCountLog2.load(memory_model::memory_order_relaxed);
+            const size_t nBucketCount = static_cast<size_t>(1) << sz;
+            if ( nBucketCount < m_Buckets.capacity()) {
+                // we may grow the bucket table
+                const size_t nLoadFactor = m_Buckets.load_factor();
+                if ( nMaxCount < max_item_count( nBucketCount, nLoadFactor ))
+                    return; // someone already have updated m_nBucketCountLog2, so stop here
+
+                m_nMaxItemCount.compare_exchange_strong( nMaxCount, max_item_count( nBucketCount << 1, nLoadFactor ),
+                                                         memory_model::memory_order_relaxed, atomics::memory_order_relaxed );
+                m_nBucketCountLog2.compare_exchange_strong( sz, sz + 1, memory_model::memory_order_relaxed, atomics::memory_order_relaxed );
             }
+            else
+                m_nMaxItemCount.store( std::numeric_limits<size_t>::max(), memory_model::memory_order_relaxed );
         }
 
         template <typename Q, typename Compare, typename Func>
@@ -489,7 +536,7 @@ namespace cds { namespace intrusive {
         }
 
         template <typename Q, typename Compare>
-        bool get_( typename gc::Guard& guard, Q const& val, Compare cmp )
+        bool get_( typename guarded_ptr::native_guard& guard, Q const& val, Compare cmp )
         {
             size_t nHash = hash_value( val );
             split_list::details::search_value_type<Q const>  sv( val, split_list::regular_hash( nHash ));
@@ -500,13 +547,13 @@ namespace cds { namespace intrusive {
         }
 
         template <typename Q>
-        bool get_( typename gc::Guard& guard, Q const& key)
+        bool get_( typename guarded_ptr::native_guard& guard, Q const& key )
         {
             return get_( guard, key, key_comparator());
         }
 
         template <typename Q, typename Less>
-        bool get_with_( typename gc::Guard& guard, Q const& key, Less )
+        bool get_with_( typename guarded_ptr::native_guard& guard, Q const& key, Less )
         {
             return get_( guard, key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
         }
@@ -536,7 +583,7 @@ namespace cds { namespace intrusive {
             dummy_node_type * pHead = get_bucket( nHash );
             assert( pHead != nullptr );
 
-            if ( m_List.erase_at( pHead, sv, cmp ) ) {
+            if ( m_List.erase_at( pHead, sv, cmp )) {
                 --m_ItemCounter;
                 m_Stat.onEraseSuccess();
                 return true;
@@ -546,14 +593,14 @@ namespace cds { namespace intrusive {
         }
 
         template <typename Q, typename Compare>
-        bool extract_( typename gc::Guard& guard, Q const& val, Compare cmp )
+        bool extract_( typename guarded_ptr::native_guard& guard, Q const& val, Compare cmp )
         {
             size_t nHash = hash_value( val );
-            split_list::details::search_value_type<Q const>  sv( val, split_list::regular_hash( nHash ));
+            split_list::details::search_value_type<Q const> sv( val, split_list::regular_hash( nHash ));
             dummy_node_type * pHead = get_bucket( nHash );
             assert( pHead != nullptr );
 
-            if ( m_List.extract_at( pHead, guard, sv, cmp ) ) {
+            if ( m_List.extract_at( pHead, guard, sv, cmp )) {
                 --m_ItemCounter;
                 m_Stat.onExtractSuccess();
                 return true;
@@ -563,28 +610,28 @@ namespace cds { namespace intrusive {
         }
 
         template <typename Q>
-        bool extract_( typename gc::Guard& guard, Q const& key)
+        bool extract_( typename guarded_ptr::native_guard& guard, Q const& key )
         {
             return extract_( guard, key, key_comparator());
         }
 
         template <typename Q, typename Less>
-        bool extract_with_( typename gc::Guard& guard, Q const& key, Less )
+        bool extract_with_( typename guarded_ptr::native_guard& guard, Q const& key, Less )
         {
-            return extract_( guard, key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+            return extract_( guard, key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
         }
-
         //@endcond
 
     public:
         /// Initialize split-ordered list of default capacity
         /**
             The default capacity is defined in bucket table constructor.
-            See \p split_list::expandable_bucket_table, \p split_list::static_ducket_table
+            See \p split_list::expandable_bucket_table, \p split_list::static_bucket_table
             which selects by \p split_list::dynamic_bucket_table option.
         */
         SplitListSet()
             : m_nBucketCountLog2(1)
+            , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()))
         {
             init();
         }
@@ -596,6 +643,7 @@ namespace cds { namespace intrusive {
             )
             : m_Buckets( nItemCount, nLoadFactor )
             , m_nBucketCountLog2(1)
+            , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()))
         {
             init();
         }
@@ -663,11 +711,12 @@ namespace cds { namespace intrusive {
             return false;
         }
 
-        /// Ensures that the \p val exists in the set
+        /// Updates the node
         /**
             The operation performs inserting or changing data with lock-free manner.
 
-            If the item \p val is not found in the set, then \p val is inserted into the set.
+            If the item \p val is not found in the set, then \p val is inserted
+            iff \p bAllowInsert is \p true.
             Otherwise, the functor \p func is called with item found.
             The functor signature is:
             \code
@@ -676,22 +725,22 @@ namespace cds { namespace intrusive {
             with arguments:
             - \p bNew - \p true if the item has been inserted, \p false otherwise
             - \p item - item of the set
-            - \p val - argument \p val passed into the \p ensure function
+            - \p val - argument \p val passed into the \p update() function
             If new item has been inserted (i.e. \p bNew is \p true) then \p item and \p val arguments
             refers to the same thing.
 
-            The functor can change non-key fields of the \p item.
+            The functor may change non-key fields of the \p item.
 
             Returns std::pair<bool, bool> where \p first is \p true if operation is successfull,
-            \p second is \p true if new item has been added or \p false if the item with \p key
-            already is in the set.
+            \p second is \p true if new item has been added or \p false if the item with \p val
+            already is in the list.
 
             @warning For \ref cds_intrusive_MichaelList_hp "MichaelList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
             \ref cds_intrusive_LazyList_hp "LazyList" provides exclusive access to inserted item and does not require any node-level
             synchronization.
         */
         template <typename Func>
-        std::pair<bool, bool> ensure( value_type& val, Func func )
+        std::pair<bool, bool> update( value_type& val, Func func, bool bAllowInsert = true )
         {
             size_t nHash = hash_value( val );
             dummy_node_type * pHead = get_bucket( nHash );
@@ -699,7 +748,7 @@ namespace cds { namespace intrusive {
 
             node_traits::to_node_ptr( val )->m_nHash = split_list::regular_hash( nHash );
 
-            std::pair<bool, bool> bRet = m_List.ensure_at( pHead, val, func );
+            std::pair<bool, bool> bRet = m_List.update_at( pHead, val, func, bAllowInsert );
             if ( bRet.first && bRet.second ) {
                 inc_item_count();
                 m_Stat.onEnsureNew();
@@ -708,6 +757,14 @@ namespace cds { namespace intrusive {
                 m_Stat.onEnsureExist();
             return bRet;
         }
+        //@cond
+        template <typename Func>
+        CDS_DEPRECATED("ensure() is deprecated, use update()")
+        std::pair<bool, bool> ensure( value_type& val, Func func )
+        {
+            return update( val, func, true );
+        }
+        //@endcond
 
         /// Unlinks the item \p val from the set
         /**
@@ -727,7 +784,7 @@ namespace cds { namespace intrusive {
             dummy_node_type * pHead = get_bucket( nHash );
             assert( pHead != nullptr );
 
-            if ( m_List.unlink_at( pHead, val ) ) {
+            if ( m_List.unlink_at( pHead, val )) {
                 --m_ItemCounter;
                 m_Stat.onEraseSuccess();
                 return true;
@@ -752,7 +809,7 @@ namespace cds { namespace intrusive {
         template <typename Q>
         bool erase( Q const& key )
         {
-            return erase_( key, key_comparator() );
+            return erase_( key, key_comparator());
         }
 
         /// Deletes the item from the set with comparing functor \p pred
@@ -766,7 +823,8 @@ namespace cds { namespace intrusive {
         template <typename Q, typename Less>
         bool erase_with( const Q& key, Less pred )
         {
-            return erase_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+            CDS_UNUSED( pred );
+            return erase_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
         }
 
         /// Deletes the item from the set
@@ -782,7 +840,6 @@ namespace cds { namespace intrusive {
                 void operator()( value_type const& item );
             };
             \endcode
-            The functor can be passed by reference with <tt>boost:ref</tt>
 
             If the item with key equal to \p key is not found the function return \p false.
 
@@ -804,19 +861,20 @@ namespace cds { namespace intrusive {
         template <typename Q, typename Less, typename Func>
         bool erase_with( Q const& key, Less pred, Func f )
         {
+            CDS_UNUSED( pred );
             return erase_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>(), f );
         }
 
         /// Extracts the item with specified \p key
         /** \anchor cds_intrusive_SplitListSet_hp_extract
             The function searches an item with key equal to \p key,
-            unlinks it from the set, and returns it in \p dest parameter.
-            If the item with key equal to \p key is not found the function returns \p false.
+            unlinks it from the set, and returns it as \p guarded_ptr.
+            If \p key is not found the function returns an empty guarded pointer.
 
             Note the compare functor should accept a parameter of type \p Q that may be not the same as \p value_type.
 
-            The \ref disposer specified in \p OrderedList class' template parameter is called automatically
-            by garbage collector \p GC when returned \ref guarded_ptr object will be destroyed or released.
+            The \p disposer specified in \p OrderedList class' template parameter is called automatically
+            by garbage collector \p GC when returned \p guarded_ptr object will be destroyed or released.
             @note Each \p guarded_ptr object uses the GC's guard that can be limited resource.
 
             Usage:
@@ -825,24 +883,26 @@ namespace cds { namespace intrusive {
             splitlist_set theSet;
             // ...
             {
-                splitlist_set::guarded_ptr gp;
-                theSet.extract( gp, 5 );
-                // Deal with gp
-                // ...
-
+                splitlist_set::guarded_ptr gp( theSet.extract( 5 ));
+                if ( gp) {
+                    // Deal with gp
+                    // ...
+                }
                 // Destructor of gp releases internal HP guard
             }
             \endcode
         */
         template <typename Q>
-        bool extract( guarded_ptr& dest, Q const& key )
+        guarded_ptr extract( Q const& key )
         {
-            return extract_( dest.guard(), key );
+            guarded_ptr gp;
+            extract_( gp.guard(), key );
+            return gp;
         }
 
         /// Extracts the item using compare functor \p pred
         /**
-            The function is an analog of \ref cds_intrusive_SplitListSet_hp_extract "extract(guarded_ptr&, Q const&)"
+            The function is an analog of \ref cds_intrusive_SplitListSet_hp_extract "extract(Q const&)"
             but \p pred predicate is used for key comparing.
 
             \p Less functor has the semantics like \p std::less but should take arguments of type \ref value_type and \p Q
@@ -850,9 +910,11 @@ namespace cds { namespace intrusive {
             \p pred must imply the same element order as the comparator used for building the set.
         */
         template <typename Q, typename Less>
-        bool extract_with( guarded_ptr& dest, Q const& key, Less pred )
+        guarded_ptr extract_with( Q const& key, Less pred )
         {
-            return extract_with_( dest.guard(), key, pred );
+            guarded_ptr gp;
+            extract_with_( gp.guard(), key, pred );
+            return gp;
         }
 
         /// Finds the key \p key
@@ -866,8 +928,6 @@ namespace cds { namespace intrusive {
             \endcode
             where \p item is the item found, \p key is the <tt>find</tt> function argument.
 
-            You can pass \p f argument by value or by reference using \p std::ref.
-
             The functor can change non-key fields of \p item. Note that the functor is only guarantee
             that \p item cannot be disposed during functor is executing.
             The functor does not serialize simultaneous access to the set \p item. If such access is
@@ -883,6 +943,13 @@ namespace cds { namespace intrusive {
         {
             return find_( key, key_comparator(), f );
         }
+        //@cond
+        template <typename Q, typename Func>
+        bool find( Q const& key, Func f )
+        {
+            return find_( key, key_comparator(), f );
+        }
+        //@endcond
 
         /// Finds the key \p key with \p pred predicate for comparing
         /**
@@ -894,46 +961,70 @@ namespace cds { namespace intrusive {
         template <typename Q, typename Less, typename Func>
         bool find_with( Q& key, Less pred, Func f )
         {
+            CDS_UNUSED( pred );
+            return find_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>(), f );
+        }
+        //@cond
+        template <typename Q, typename Less, typename Func>
+        bool find_with( Q const& key, Less pred, Func f )
+        {
+            CDS_UNUSED( pred );
             return find_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>(), f );
         }
+        //@endcond
 
-        /// Finds the key \p key
-        /** \anchor cds_intrusive_SplitListSet_hp_find_val
+        /// Checks whether the set contains \p key
+        /**
             The function searches the item with key equal to \p key
             and returns \p true if it is found, and \p false otherwise.
 
             Note the hash functor specified for class \p Traits template parameter
             should accept a parameter of type \p Q that can be not the same as \p value_type.
-            Otherwise, you may use \p find_with functions with explicit predicate for key comparing.
+            Otherwise, you may use \p contains( Q const&, Less pred ) functions with explicit predicate for key comparing.
         */
         template <typename Q>
+        bool contains( Q const& key )
+        {
+            return find_( key, key_comparator());
+        }
+        //@cond
+        template <typename Q>
+        CDS_DEPRECATED("deprecated, use contains()")
         bool find( Q const& key )
         {
-            return find_( key, key_comparator() );
+            return contains( key );
         }
+        //@endcond
 
-        /// Finds the key \p key with \p pred predicate for comparing
+        /// Checks whether the set contains \p key using \p pred predicate for searching
         /**
-            The function is an analog of \ref cds_intrusive_SplitListSet_hp_find_val "find(Q const&)"
-            but \p cmp is used for key compare.
-            \p Less has the interface like \p std::less.
-            \p cmp must imply the same element order as the comparator used for building the set.
+            The function is an analog of <tt>contains( key )</tt> but \p pred is used for key comparing.
+            \p Less functor has the interface like \p std::less.
+            \p Less must imply the same element order as the comparator used for building the set.
         */
         template <typename Q, typename Less>
+        bool contains( Q const& key, Less pred )
+        {
+            CDS_UNUSED( pred );
+            return find_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
+        }
+        //@cond
+        template <typename Q, typename Less>
+        CDS_DEPRECATED("deprecated, use contains()")
         bool find_with( Q const& key, Less pred )
         {
-            return find_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+            return contains( key, pred );
         }
+        //@endcond
 
         /// Finds the key \p key and return the item found
         /** \anchor cds_intrusive_SplitListSet_hp_get
             The function searches the item with key equal to \p key
-            and assigns the item found to guarded pointer \p ptr.
-            The function returns \p true if \p key is found, and \p false otherwise.
-            If \p key is not found the \p ptr parameter is not changed.
+            and returns the item found as \p guarded_ptr.
+            If \p key is not found the function returns an empty guarded pointer.
 
-            The \ref disposer specified in \p OrderedList class' template parameter is called
-            by garbage collector \p GC automatically when returned \ref guarded_ptr object
+            The \p disposer specified in \p OrderedList class' template parameter is called
+            by garbage collector \p GC automatically when returned \p guarded_ptr object
             will be destroyed or released.
             @note Each \p guarded_ptr object uses one GC's guard which can be limited resource.
 
@@ -943,8 +1034,8 @@ namespace cds { namespace intrusive {
             splitlist_set theSet;
             // ...
             {
-                splitlist_set::guarded_ptr gp;
-                if ( theSet.get( gp, 5 )) {
+                splitlist_set::guarded_ptr gp = theSet.get( 5 );
+                if ( gp ) {
                     // Deal with gp
                     //...
                 }
@@ -956,14 +1047,16 @@ namespace cds { namespace intrusive {
             should accept a parameter of type \p Q that can be not the same as \p value_type.
         */
         template <typename Q>
-        bool get( guarded_ptr& ptr, Q const& key )
+        guarded_ptr get( Q const& key )
         {
-            return get_( ptr.guard(), key );
+            guarded_ptr gp;
+            get_( gp.guard(), key );
+            return gp;
         }
 
         /// Finds the key \p key and return the item found
         /**
-            The function is an analog of \ref cds_intrusive_SplitListSet_hp_get "get( guarded_ptr& ptr, Q const&)"
+            The function is an analog of \ref cds_intrusive_SplitListSet_hp_get "get( Q const&)"
             but \p pred is used for comparing the keys.
 
             \p Less functor has the semantics like \p std::less but should take arguments of type \ref value_type and \p Q
@@ -971,9 +1064,11 @@ namespace cds { namespace intrusive {
             \p pred must imply the same element order as the comparator used for building the set.
         */
         template <typename Q, typename Less>
-        bool get_with( guarded_ptr& ptr, Q const& key, Less pred )
+        guarded_ptr get_with( Q const& key, Less pred )
         {
-            return get_with_( ptr.guard(), key, pred );
+            guarded_ptr gp;
+            get_with_( gp.guard(), key, pred );
+            return gp;
         }
 
         /// Returns item count in the set
@@ -1002,7 +1097,7 @@ namespace cds { namespace intrusive {
         void clear()
         {
             iterator it = begin();
-            while ( it != end() ) {
+            while ( it != end()) {
                 iterator i(it);
                 ++i;
                 unlink( *it );
@@ -1065,7 +1160,7 @@ namespace cds { namespace intrusive {
         */
         iterator begin()
         {
-            return iterator( m_List.begin(), m_List.end() );
+            return iterator( m_List.begin(), m_List.end());
         }
 
         /// Returns an iterator that addresses the location succeeding the last element in a split-list
@@ -1077,7 +1172,7 @@ namespace cds { namespace intrusive {
         */
         iterator end()
         {
-            return iterator( m_List.end(), m_List.end() );
+            return iterator( m_List.end(), m_List.end());
         }
 
         /// Returns a forward const iterator addressing the first element in a split-list
@@ -1088,7 +1183,7 @@ namespace cds { namespace intrusive {
         /// Returns a forward const iterator addressing the first element in a split-list
         const_iterator cbegin() const
         {
-            return const_iterator( m_List.cbegin(), m_List.cend() );
+            return const_iterator( m_List.cbegin(), m_List.cend());
         }
 
         /// Returns an const iterator that addresses the location succeeding the last element in a split-list
@@ -1099,11 +1194,11 @@ namespace cds { namespace intrusive {
         /// Returns an const iterator that addresses the location succeeding the last element in a split-list
         const_iterator cend() const
         {
-            return const_iterator( m_List.cend(), m_List.cend() );
+            return const_iterator( m_List.cend(), m_List.cend());
         }
 
     };
 
 }}  // namespace cds::intrusive
 
-#endif // #ifndef __CDS_INTRUSIVE_SPLIT_LIST_H
+#endif // #ifndef CDSLIB_INTRUSIVE_SPLIT_LIST_H