Fixed doc

diff --git a/cds/container/impl/lazy_list.h b/cds/container/impl/lazy_list.h
index c68f6684140c9df8a3d532f8fd9570334537d75e..45ddb68e35ea40d102d1340635eee682ecdb7fe8 100644 (file)
--- 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<true>     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 287ee4b1cdf821ad1ae9fc1ccdb726c0d61f3e0f..3dc503f9b49568f17eea35bed40fdf969142f811 100644 (file)
--- 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 1f49fbdd7047a454228c3b712f3f732cc0e7133d..2d08ef03688ee500e7e749db5f762869a8550139 100644 (file)
--- 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<false>    iterator;
 
         /// Const forward iterator
@@ -290,8 +296,6 @@ namespace cds { namespace container {
         */
         typedef iterator_type<true>     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 82aa2ca7818b8531a281557f0eb74ee646306300..d4510a4e59d5f4b1a5728e0d77c41d437a71ca2c 100644 (file)
--- 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<false>    iterator;
 
         /// Const forward iterator
         typedef iterator_type<true>     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 66a93fabb9e61f2024da0abd55c6bf7c92935ada..24970fc6d97d61cce9a9fad9706654f7be5612ea 100644 (file)
--- 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<false>    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 84f0b5540c46e774580fb653d6fa933b8f71080d..63be73333fefc460b87f57b39fad5d24fccfa6c0 100644 (file)
--- 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 1742f21d4a0fbefa828c62b4bd81338b4fba3d8d..1981bc542d0e29f107cd698400ab8b091de1f510 100644 (file)
--- 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<false>    iterator;
+
         /// Const forward iterator
         typedef iterator_type<true>     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