From 3db826fe29981d1adfd5869a82382b256f580d39 Mon Sep 17 00:00:00 2001 From: khizmax Date: Wed, 9 Mar 2016 19:18:39 +0300 Subject: [PATCH] Fixed doc --- cds/container/impl/lazy_list.h | 5 +++-- cds/container/impl/michael_list.h | 1 + cds/container/lazy_list_rcu.h | 8 ++++++-- cds/container/michael_list_rcu.h | 8 ++++++-- cds/intrusive/impl/lazy_list.h | 15 +++++++++------ cds/intrusive/impl/michael_list.h | 9 ++++++--- cds/intrusive/lazy_list_rcu.h | 16 ++++++++++++---- 7 files changed, 43 insertions(+), 19 deletions(-) diff --git a/cds/container/impl/lazy_list.h b/cds/container/impl/lazy_list.h index c68f6684..45ddb68e 100644 --- a/cds/container/impl/lazy_list.h +++ b/cds/container/impl/lazy_list.h @@ -277,6 +277,8 @@ namespace cds { namespace container { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator /** The forward iterator for lazy list has some features: @@ -287,6 +289,7 @@ namespace cds { namespace container { - The iterator 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 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. */ @@ -298,8 +301,6 @@ namespace cds { namespace container { */ typedef iterator_type const_iterator; - ///@name Forward iterators (only for debugging purpose) - //@{ /// Returns a forward iterator addressing the first element in a list /** For empty list \code begin() == end() \endcode diff --git a/cds/container/impl/michael_list.h b/cds/container/impl/michael_list.h index 287ee4b1..3dc503f9 100644 --- a/cds/container/impl/michael_list.h +++ b/cds/container/impl/michael_list.h @@ -271,6 +271,7 @@ namespace cds { namespace container { - The iterator 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 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. */ diff --git a/cds/container/lazy_list_rcu.h b/cds/container/lazy_list_rcu.h index 1f49fbdd..2d08ef03 100644 --- a/cds/container/lazy_list_rcu.h +++ b/cds/container/lazy_list_rcu.h @@ -281,7 +281,13 @@ namespace cds { namespace container { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator + /** + You may safely use iterators in multi-threaded environment only under RCU lock. + Otherwise, a crash is possible if another thread deletes the item the iterator points to. + */ typedef iterator_type iterator; /// Const forward iterator @@ -290,8 +296,6 @@ namespace cds { namespace container { */ typedef iterator_type const_iterator; - ///@name Forward iterators (only for debugging purpose) - //@{ /// Returns a forward iterator addressing the first element in a list /** For empty list \code begin() == end() \endcode diff --git a/cds/container/michael_list_rcu.h b/cds/container/michael_list_rcu.h index 82aa2ca7..d4510a4e 100644 --- a/cds/container/michael_list_rcu.h +++ b/cds/container/michael_list_rcu.h @@ -297,14 +297,18 @@ namespace cds { namespace container { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator + /** + You may safely use iterators in multi-threaded environment only under RCU lock. + Otherwise, a crash is possible if another thread deletes the item the iterator points to. + */ typedef iterator_type iterator; /// Const forward iterator typedef iterator_type const_iterator; - ///@name Forward iterators (only for debugging purpose) - //@{ /// Returns a forward iterator addressing the first element in a list /** For empty list \code begin() == end() \endcode diff --git a/cds/intrusive/impl/lazy_list.h b/cds/intrusive/impl/lazy_list.h index 66a93fab..24970fc6 100644 --- a/cds/intrusive/impl/lazy_list.h +++ b/cds/intrusive/impl/lazy_list.h @@ -409,6 +409,8 @@ namespace cds { namespace intrusive { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator /** The forward iterator for lazy list has some features: @@ -419,9 +421,9 @@ namespace cds { namespace intrusive { - The iterator 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 list. + 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 iterator; /// Const forward iterator @@ -454,28 +456,29 @@ namespace cds { namespace intrusive { } /// Returns a forward const iterator addressing the first element in a list - //@{ const_iterator begin() const { return get_const_begin(); } + + /// Returns a forward const iterator addressing the first element in a list const_iterator cbegin() const { return get_const_begin(); } - //@} /// Returns an const iterator that addresses the location succeeding the last element in a list - //@{ const_iterator end() const { return get_const_end(); } + + /// Returns an const iterator that addresses the location succeeding the last element in a list const_iterator cend() const { return get_const_end(); } - //@} + //@} private: //@cond diff --git a/cds/intrusive/impl/michael_list.h b/cds/intrusive/impl/michael_list.h index 84f0b554..63be7333 100644 --- a/cds/intrusive/impl/michael_list.h +++ b/cds/intrusive/impl/michael_list.h @@ -408,6 +408,8 @@ namespace cds { namespace intrusive { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator /** The forward iterator for Michael's list has some features: @@ -417,10 +419,10 @@ namespace cds { namespace intrusive { may be thrown if the limit of guard count per thread is exceeded. - The iterator cannot be moved across thread boundary since 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 list. + deleting operations there is no guarantee that you iterate all item in the list. + 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. The iterator interface: \code @@ -502,6 +504,7 @@ namespace cds { namespace intrusive { { return const_iterator(); } + //@} public: /// Default constructor initializes empty list diff --git a/cds/intrusive/lazy_list_rcu.h b/cds/intrusive/lazy_list_rcu.h index 1742f21d..1981bc54 100644 --- a/cds/intrusive/lazy_list_rcu.h +++ b/cds/intrusive/lazy_list_rcu.h @@ -352,8 +352,15 @@ namespace cds { namespace intrusive { //@endcond public: + ///@name Forward iterators (only for debugging purpose) + //@{ /// Forward iterator + /** + You may safely use iterators in multi-threaded environment only under RCU lock. + Otherwise, a crash is possible if another thread deletes the item the iterator points to. + */ typedef iterator_type iterator; + /// Const forward iterator typedef iterator_type const_iterator; @@ -381,28 +388,29 @@ namespace cds { namespace intrusive { } /// Returns a forward const iterator addressing the first element in a list - //@{ const_iterator begin() const { return get_const_begin(); } + + /// Returns a forward const iterator addressing the first element in a list const_iterator cbegin() const { return get_const_begin(); } - //@} /// Returns an const iterator that addresses the location succeeding the last element in a list - //@{ const_iterator end() const { return get_const_end(); } + + /// Returns an const iterator that addresses the location succeeding the last element in a list const_iterator cend() const { return get_const_end(); } - //@} + //@} private: //@cond -- 2.34.1