From: khizmax Date: Sat, 19 Mar 2016 07:57:57 +0000 (+0300) Subject: Docfix X-Git-Tag: v2.2.0~334 X-Git-Url: http://plrg.eecs.uci.edu/git/?a=commitdiff_plain;h=0bae61829528ed14ffee72c2e11ab0f9ce088cc1;p=libcds.git Docfix --- diff --git a/cds/container/split_list_set.h b/cds/container/split_list_set.h index a68cd89d..5003474b 100644 --- a/cds/container/split_list_set.h +++ b/cds/container/split_list_set.h @@ -249,26 +249,13 @@ namespace cds { namespace container { //@endcond protected: - /// Forward iterator - /** - \p IsConst - constness boolean flag - - The forward iterator for a split-list has the following features: - - it has no post-increment operator - - it depends on underlying ordered list iterator - - The iterator object cannot be moved across thread boundary since it contains 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. - - Therefore, the use of iterators in concurrent environment is not good idea. Use it for debug purpose only. - */ + //@cond template class iterator_type: protected base_class::template iterator_type { - //@cond typedef typename base_class::template iterator_type iterator_base_class; friend class SplitListSet; - //@endcond + public: /// Value pointer type (const for const iterator) typedef typename cds::details::make_const_type::pointer value_ptr; @@ -286,11 +273,9 @@ namespace cds { namespace container { {} protected: - //@cond explicit iterator_type( iterator_base_class const& src ) : iterator_base_class( src ) {} - //@endcond public: /// Dereference operator @@ -333,6 +318,7 @@ namespace cds { namespace container { return iterator_base_class::operator!=(i); } }; + //@endcond public: /// Initializes split-ordered list of default capacity @@ -354,7 +340,48 @@ namespace cds { namespace container { {} public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator + /** + The forward iterator for a split-list has the following features: + - it has no post-increment operator + - it depends on underlying ordered list iterator + - The iterator object cannot be moved across thread boundary because it contains 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. + Moreover, a crash is possible when you try to iterate the next element that has been deleted by concurrent thread. + + @warning Use this iterator on the concurrent container for debugging purpose only. + + The iterator interface: + \code + class iterator { + public: + // Default constructor + iterator(); + + // Copy construtor + iterator( iterator const& src ); + + // Dereference operator + value_type * operator ->() const; + + // Dereference operator + value_type& operator *() const; + + // Preincrement operator + iterator& operator ++(); + + // Assignment operator + iterator& operator = (iterator const& src); + + // Equality operators + bool operator ==(iterator const& i ) const; + bool operator !=(iterator const& i ) const; + }; + \endcode + */ typedef iterator_type iterator; /// Const forward iterator @@ -401,6 +428,7 @@ namespace cds { namespace container { { return const_iterator( base_class::cend()); } + //@} public: /// Inserts new node diff --git a/cds/container/split_list_set_nogc.h b/cds/container/split_list_set_nogc.h index 8a83494f..4b74adb3 100644 --- a/cds/container/split_list_set_nogc.h +++ b/cds/container/split_list_set_nogc.h @@ -137,21 +137,13 @@ namespace cds { namespace container { {} protected: - /// Forward iterator - /** - \p IsConst - constness boolean flag - - The forward iterator has the following features: - - it has no post-increment operator - - it depends on underlying ordered list iterator - */ + //@cond template class iterator_type: protected base_class::template iterator_type { - //@cond typedef typename base_class::template iterator_type iterator_base_class; friend class SplitListSet; - //@endcond + public: /// Value pointer type (const for const iterator) typedef typename cds::details::make_const_type::pointer value_ptr; @@ -169,11 +161,9 @@ namespace cds { namespace container { {} protected: - //@cond explicit iterator_type( iterator_base_class const& src ) : iterator_base_class( src ) {} - //@endcond public: /// Dereference operator @@ -216,9 +206,45 @@ namespace cds { namespace container { return iterator_base_class::operator!=(i); } }; + //@endcond public: + ///@name Forward iterators + //@{ /// Forward iterator + /** + The forward iterator for Michael's set is based on \p OrderedList forward iterator and has some features: + - it has no post-increment operator + - it iterates items in unordered fashion + + The iterator interface: + \code + class iterator { + public: + // Default constructor + iterator(); + + // Copy construtor + iterator( iterator const& src ); + + // Dereference operator + value_type * operator ->() const; + + // Dereference operator + value_type& operator *() const; + + // Preincrement operator + iterator& operator ++(); + + // Assignment operator + iterator& operator = (iterator const& src); + + // Equality operators + bool operator ==(iterator const& i ) const; + bool operator !=(iterator const& i ) const; + }; + \endcode + */ typedef iterator_type iterator; /// Const forward iterator @@ -265,6 +291,7 @@ namespace cds { namespace container { { return const_iterator( base_class::cend() ); } + //@} protected: //@cond diff --git a/cds/container/split_list_set_rcu.h b/cds/container/split_list_set_rcu.h index cec9f0b2..c2625cf9 100644 --- a/cds/container/split_list_set_rcu.h +++ b/cds/container/split_list_set_rcu.h @@ -366,26 +366,13 @@ namespace cds { namespace container { //@endcond protected: - /// Forward iterator - /** - \p IsConst - constness boolean flag - - The forward iterator for a split-list has the following features: - - it has no post-increment operator - - it depends on underlying ordered list iterator - - it is safe to iterate only inside RCU critical section - - deleting an item pointed by the iterator can cause to deadlock - - Therefore, the use of iterators in concurrent environment is not good idea. - Use it for debug purpose only. - */ + //@cond template class iterator_type: protected base_class::template iterator_type { - //@cond typedef typename base_class::template iterator_type iterator_base_class; friend class SplitListSet; - //@endcond + public: /// Value pointer type (const for const iterator) typedef typename cds::details::make_const_type::pointer value_ptr; @@ -403,11 +390,9 @@ namespace cds { namespace container { {} protected: - //@cond explicit iterator_type( iterator_base_class const& src ) : iterator_base_class( src ) {} - //@endcond public: /// Dereference operator @@ -450,6 +435,7 @@ namespace cds { namespace container { return iterator_base_class::operator!=(i); } }; + //@endcond public: /// Initializes split-ordered list of default capacity @@ -471,8 +457,49 @@ namespace cds { namespace container { {} public: - typedef iterator_type iterator ; ///< Forward iterator - typedef iterator_type const_iterator ; ///< Forward const iterator + ///@name Forward iterators (thread-safe under RCU lock) + //@{ + /// Forward iterator + /** + The forward iterator for Michael's set is based on \p OrderedList forward iterator and has some features: + - it has no post-increment operator + - it iterates items in unordered fashion + + You may safely use iterators in multi-threaded environment only under RCU lock. + Otherwise, a crash is possible if another thread deletes the element the iterator points to. + + The iterator interface: + \code + class iterator { + public: + // Default constructor + iterator(); + + // Copy construtor + iterator( iterator const& src ); + + // Dereference operator + value_type * operator ->() const; + + // Dereference operator + value_type& operator *() const; + + // Preincrement operator + iterator& operator ++(); + + // Assignment operator + iterator& operator = (iterator const& src); + + // Equality operators + bool operator ==(iterator const& i ) const; + bool operator !=(iterator const& i ) const; + }; + \endcode + */ + typedef iterator_type iterator; + + /// Forward const iterator + typedef iterator_type const_iterator; /// Returns a forward iterator addressing the first element in a set /** @@ -515,6 +542,7 @@ namespace cds { namespace container { { return const_iterator( base_class::cend() ); } + //@} public: /// Inserts new node