-//$$CDS-header$$
+/*
+ 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 <cds/intrusive/details/split_list_base.h>
#include <limits>
+#include <cds/intrusive/details/split_list_base.h>
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
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.
typedef GC gc; ///< Garbage collector
typedef Traits traits; ///< Set traits
- //@cond
- typedef cds::intrusive::split_list::implementation_tag implementation_tag;
- //@endcond
-
protected:
//@cond
typedef split_list::details::rebind_list_traits<OrderedList, traits> wrapped_ordered_list;
typedef typename traits::stat stat; ///< Internal statistics, see \p spit_list::stat
typedef typename ordered_list::guarded_ptr guarded_ptr; ///< Guarded pointer
+ /// Count of hazard pointer required
+ static CDS_CONSTEXPR const size_t c_nHazardPtrCount = ordered_list::c_nHazardPtrCount + 4; // +4 - for iterators
+
protected:
typedef typename ordered_list::node_type list_node_type; ///< Node type as declared in ordered list
typedef split_list::node<list_node_type> node_type; ///< split-list node type
}
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 )
}
template <typename Q, typename Compare>
- bool extract_at( dummy_node_type * pHead, typename guarded_ptr::native_guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
+ guarded_ptr extract_at( dummy_node_type * pHead, split_list::details::search_value_type<Q> const& val, Compare cmp )
{
assert( pHead != nullptr );
bucket_head_type h(pHead);
- return base_class::extract_at( h, guard, val, cmp );
+ return base_class::extract_at( h, val, cmp );
}
template <typename Q, typename Compare, typename Func>
}
template <typename Q, typename Compare>
- bool get_at( dummy_node_type * pHead, typename guarded_ptr::native_guard& guard, split_list::details::search_value_type<Q> const& val, Compare cmp )
+ guarded_ptr get_at( dummy_node_type * pHead, split_list::details::search_value_type<Q> const& val, Compare cmp )
{
assert( pHead != nullptr );
bucket_head_type h(pHead);
- return base_class::get_at( h, guard, val, cmp );
+ return base_class::get_at( h, val, cmp );
}
bool insert_aux_node( dummy_node_type * pNode )
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 )
// 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;
if ( pHead == nullptr )
pHead = init_bucket( nBucket );
- assert( pHead->is_dummy() );
+ assert( pHead->is_dummy());
return pHead;
}
if ( ++m_ItemCounter <= nMaxCount )
return;
- const size_t nLoadFactor = m_Buckets.load_factor();
size_t sz = m_nBucketCountLog2.load(memory_model::memory_order_relaxed);
const size_t nBucketCount = static_cast<size_t>(1) << sz;
- if ( nMaxCount < max_item_count( nBucketCount, nLoadFactor ))
- return; // someone already have updated m_nBucketCountLog2, so stop here
-
- const size_t nNewMaxCount = (nBucketCount < m_Buckets.capacity()) ? max_item_count( nBucketCount << 1, nLoadFactor )
- : std::numeric_limits<size_t>::max();
- m_nMaxItemCount.compare_exchange_strong( nMaxCount, nNewMaxCount, memory_model::memory_order_relaxed,
- memory_model::memory_order_relaxed );
- m_nBucketCountLog2.compare_exchange_strong( sz, sz + 1, memory_model::memory_order_relaxed, memory_model::memory_order_relaxed );
+ 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>
}
template <typename Q, typename Compare>
- bool get_( typename guarded_ptr::native_guard& guard, Q const& val, Compare cmp )
+ guarded_ptr get_( 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 ));
dummy_node_type * pHead = get_bucket( nHash );
assert( pHead != nullptr );
- return m_Stat.onFind( m_List.get_at( pHead, guard, sv, cmp ));
+ guarded_ptr gp = m_List.get_at( pHead, sv, cmp );
+ m_Stat.onFind( !gp.empty() );
+ return gp;
}
template <typename Q>
- bool get_( typename guarded_ptr::native_guard& guard, Q const& key )
+ guarded_ptr get_( Q const& key )
{
- return get_( guard, key, key_comparator());
+ return get_( key, key_comparator());
}
template <typename Q, typename Less>
- bool get_with_( typename guarded_ptr::native_guard& guard, Q const& key, Less )
+ guarded_ptr get_with_( Q const& key, Less )
{
- return get_( guard, key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
+ return get_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
}
template <typename Q, typename Compare, typename Func>
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;
}
template <typename Q, typename Compare>
- bool extract_( typename guarded_ptr::native_guard& guard, Q const& val, Compare cmp )
+ guarded_ptr extract_( 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 ));
dummy_node_type * pHead = get_bucket( nHash );
assert( pHead != nullptr );
- if ( m_List.extract_at( pHead, guard, sv, cmp ) ) {
+ guarded_ptr gp = m_List.extract_at( pHead, sv, cmp );
+ if ( gp ) {
--m_ItemCounter;
m_Stat.onExtractSuccess();
- return true;
}
- m_Stat.onExtractFailed();
- return false;
+ else
+ m_Stat.onExtractFailed();
+ return gp;
}
template <typename Q>
- bool extract_( typename guarded_ptr::native_guard& guard, Q const& key )
+ guarded_ptr extract_( Q const& key )
{
- return extract_( guard, key, key_comparator());
+ return extract_( key, key_comparator());
}
template <typename Q, typename Less>
- bool extract_with_( typename guarded_ptr::native_guard& guard, Q const& key, Less )
+ guarded_ptr extract_with_( Q const& key, Less )
{
- return extract_( guard, key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+ return extract_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
}
//@endcond
*/
SplitListSet()
: m_nBucketCountLog2(1)
- , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()) )
+ , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()))
{
init();
}
)
: m_Buckets( nItemCount, nLoadFactor )
, m_nBucketCountLog2(1)
- , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()) )
+ , m_nMaxItemCount( max_item_count(2, m_Buckets.load_factor()))
{
init();
}
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
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.
+ Returns std::pair<bool, bool> where \p first is \p true if operation is successful,
+ \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 );
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();
+ m_Stat.onUpdateNew();
}
else
- m_Stat.onEnsureExist();
+ m_Stat.onUpdateExist();
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
/**
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;
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
bool erase_with( const Q& key, Less pred )
{
CDS_UNUSED( pred );
- return erase_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+ return erase_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>());
}
/// Deletes the item from the set
template <typename Q>
guarded_ptr extract( Q const& key )
{
- guarded_ptr gp;
- extract_( gp.guard(), key );
- return gp;
+ return extract_( key );
}
/// Extracts the item using compare functor \p pred
template <typename Q, typename Less>
guarded_ptr extract_with( Q const& key, Less pred )
{
- guarded_ptr gp;
- extract_with_( gp.guard(), key, pred );
- return gp;
+ return extract_with_( key, pred );
}
/// Finds the key \p key
}
//@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 find_with( Q const& key, Less pred )
+ bool contains( Q const& key, Less pred )
{
CDS_UNUSED( pred );
- return find_( key, typename wrapped_ordered_list::template make_compare_from_less<Less>() );
+ 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 contains( key, pred );
}
+ //@endcond
/// Finds the key \p key and return the item found
/** \anchor cds_intrusive_SplitListSet_hp_get
template <typename Q>
guarded_ptr get( Q const& key )
{
- guarded_ptr gp;
- get_( gp.guard(), key );
- return gp;
+ return get_( key );
}
/// Finds the key \p key and return the item found
template <typename Q, typename Less>
guarded_ptr get_with( Q const& key, Less pred )
{
- guarded_ptr gp;
- get_with_( gp.guard(), key, pred );
- return gp;
+ return get_with_( key, pred );
}
/// Returns item count in the set
void clear()
{
iterator it = begin();
- while ( it != end() ) {
+ while ( it != end()) {
iterator i(it);
++i;
unlink( *it );
};
//@endcond
public:
+ ///@name Forward iterators (only for debugging purpose)
+ //@{
/// Forward iterator
/**
The forward iterator for a split-list has some features:
- it depends on iterator of underlying \p OrderedList
- The iterator cannot be moved across thread boundary since it may contain GC's guard that is thread-private GC data.
- Iterator ensures thread-safety even if you delete the item that iterator points to. However, in case of concurrent
- deleting operations it is no guarantee that you iterate all item in the split-list.
+ deleting operations it is no guarantee that you iterate all item in the set.
+ Moreover, a crash is possible when you try to iterate the next element that has been deleted by concurrent thread.
- Therefore, the use of iterators in concurrent environment is not good idea. Use the iterator on the concurrent container
- for debug purpose only.
+ @warning Use this iterator on the concurrent container for debugging purpose only.
*/
typedef iterator_type<false> iterator;
+
/// Const forward iterator
/**
For iterator's features and requirements see \ref iterator
*/
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
*/
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
/// 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
/// 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