From 7a91849c571fa6c18002555350a49d7625c1e443 Mon Sep 17 00:00:00 2001 From: khizmax Date: Tue, 15 Mar 2016 12:09:25 +0300 Subject: [PATCH] Docfix --- cds/container/michael_set.h | 54 +++++++++++++++++++++++++++++--- cds/container/michael_set_nogc.h | 39 ++++++++++++++++++++--- cds/container/michael_set_rcu.h | 46 +++++++++++++++++++++------ cds/intrusive/michael_set.h | 2 +- cds/intrusive/michael_set_nogc.h | 28 +++++++++++++++++ cds/intrusive/michael_set_rcu.h | 28 +++++++++++++++++ 6 files changed, 179 insertions(+), 18 deletions(-) diff --git a/cds/container/michael_set.h b/cds/container/michael_set.h index 2ecdcf6a..b0b0d507 100644 --- a/cds/container/michael_set.h +++ b/cds/container/michael_set.h @@ -251,6 +251,51 @@ namespace cds { namespace container { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ + /// Forward iterator + /** + The forward iterator for Michael's set has some features: + - it has no post-increment operator + - to protect the value, the iterator contains a GC-specific guard + another guard is required locally for increment operator. + For some GC (like as \p gc::HP), a guard is a limited resource per thread, so an exception (or assertion) "no free guard" + may be thrown if the limit of guard count per thread is exceeded. + - The iterator cannot be moved across thread boundary because it contains thread-private GC's guard. + - Iterator ensures thread-safety even if you delete the item the iterator points to. However, in case of concurrent + deleting operations there 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. + + @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 + */ + /// Forward iterator typedef michael_set::details::iterator< bucket_type, false > iterator; @@ -278,28 +323,29 @@ namespace cds { namespace container { } /// Returns a forward const iterator addressing the first element in a set - //@{ const_iterator begin() const { return get_const_begin(); } + + /// Returns a forward const iterator addressing the first element in a set const_iterator cbegin() const { return get_const_begin(); } - //@} /// Returns an const iterator that addresses the location succeeding the last element in a set - //@{ const_iterator end() const { return get_const_end(); } + + /// Returns an const iterator that addresses the location succeeding the last element in a set const_iterator cend() const { return get_const_end(); } - //@} + //@} private: //@cond diff --git a/cds/container/michael_set_nogc.h b/cds/container/michael_set_nogc.h index 1dd1c103..c4ae09b8 100644 --- a/cds/container/michael_set_nogc.h +++ b/cds/container/michael_set_nogc.h @@ -107,11 +107,41 @@ namespace cds { namespace container { //@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 michael_set::details::iterator< bucket_type, false > iterator; @@ -142,28 +172,29 @@ namespace cds { namespace container { } /// Returns a forward const iterator addressing the first element in a set - //@{ const_iterator begin() const { return get_const_begin(); } + + /// Returns a forward const iterator addressing the first element in a set const_iterator cbegin() const { return get_const_begin(); } - //@} /// Returns an const iterator that addresses the location succeeding the last element in a set - //@{ const_iterator end() const { return get_const_end(); } + + /// Returns an const iterator that addresses the location succeeding the last element in a set const_iterator cend() const { return get_const_end(); } - //@} + //@} private: //@cond diff --git a/cds/container/michael_set_rcu.h b/cds/container/michael_set_rcu.h index 687c79a3..0ea938b5 100644 --- a/cds/container/michael_set_rcu.h +++ b/cds/container/michael_set_rcu.h @@ -187,17 +187,44 @@ namespace cds { namespace container { } //@endcond public: + ///@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 - - 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 set. - Therefore, the use of iterators in concurrent environment is not good idea. Use the iterator for the concurrent container - for debug purpose only. + 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 michael_set::details::iterator< bucket_type, false > iterator; @@ -225,28 +252,29 @@ namespace cds { namespace container { } /// Returns a forward const iterator addressing the first element in a set - //@{ const_iterator begin() const { return get_const_begin(); } + + /// Returns a forward const iterator addressing the first element in a set const_iterator cbegin() const { return get_const_begin(); } - //@} /// Returns an const iterator that addresses the location succeeding the last element in a set - //@{ const_iterator end() const { return get_const_end(); } + + /// Returns an const iterator that addresses the location succeeding the last element in a set const_iterator cend() const { return get_const_end(); } - //@} + //@} private: //@cond diff --git a/cds/intrusive/michael_set.h b/cds/intrusive/michael_set.h index 16cac8f9..201a8275 100644 --- a/cds/intrusive/michael_set.h +++ b/cds/intrusive/michael_set.h @@ -302,7 +302,7 @@ namespace cds { namespace intrusive { 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 cannot be moved across thread boundary since it may contain GC's guard that is thread-private GC data. + - The iterator cannot be moved across thread boundary because 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 set. Moreover, a crash is possible when you try to iterate the next element that has been deleted by concurrent thread. diff --git a/cds/intrusive/michael_set_nogc.h b/cds/intrusive/michael_set_nogc.h index 65cdd4f4..b30bff95 100644 --- a/cds/intrusive/michael_set_nogc.h +++ b/cds/intrusive/michael_set_nogc.h @@ -109,6 +109,34 @@ namespace cds { namespace intrusive { 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 michael_set::details::iterator< bucket_type, false > iterator; diff --git a/cds/intrusive/michael_set_rcu.h b/cds/intrusive/michael_set_rcu.h index 9157f02d..4b762fea 100644 --- a/cds/intrusive/michael_set_rcu.h +++ b/cds/intrusive/michael_set_rcu.h @@ -166,6 +166,34 @@ namespace cds { namespace intrusive { 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 michael_set::details::iterator< bucket_type, false > iterator; -- 2.34.1