From: khizmax <libcds.dev@gmail.com>
Date: Sat, 15 Nov 2014 15:22:48 +0000 (+0300)
Subject: Hazard Pointer docfix
X-Git-Tag: v2.0.0~84
X-Git-Url: http://plrg.eecs.uci.edu/git/?p=libcds.git;a=commitdiff_plain;h=408a5149e52b7f2d2b49a745bd2c0123f3f97873;hp=ef671b8b2db9357d83de1a0fae3044f1d2b9d6f7

Hazard Pointer docfix
---

diff --git a/cds/gc/details/dhp.h b/cds/gc/details/dhp.h
index 8e117c7a..70e70c5d 100644
--- a/cds/gc/details/dhp.h
+++ b/cds/gc/details/dhp.h
@@ -15,6 +15,7 @@
 #   pragma warning(disable:4251)    // C4251: 'identifier' : class 'type' needs to have dll-interface to be used by clients of class 'type2'
 #endif
 
+//@cond
 namespace cds { namespace gc {
 
     /// Dynamic Hazard Pointer reclamation schema
@@ -72,7 +73,6 @@ namespace cds { namespace gc {
 
                 guard_data *             pThreadNext ;   ///< next item of thread's local list of guards
 
-                //@cond
                 guard_data() CDS_NOEXCEPT
                     : pPost( nullptr )
                     , pGlobalNext( nullptr )
@@ -84,7 +84,6 @@ namespace cds { namespace gc {
                 {
                     pPost.store( nullptr, atomics::memory_order_relaxed );
                 }
-                //@endcond
 
                 /// Checks if the guard is free, that is, it does not contain any pointer guarded
                 bool isFree() const CDS_NOEXCEPT
@@ -250,7 +249,6 @@ namespace cds { namespace gc {
                 atomics::atomic<size_t>              m_nItemCount;   ///< buffer's item count
 
             public:
-                //@cond
                 CDS_CONSTEXPR retired_ptr_buffer() CDS_NOEXCEPT
                     : m_pHead( nullptr )
                     , m_nItemCount(0)
@@ -260,7 +258,6 @@ namespace cds { namespace gc {
                 {
                     assert( m_pHead.load( atomics::memory_order_relaxed ) == nullptr );
                 }
-                //@endcond
 
                 /// Pushes new node into the buffer. Returns current buffer size
                 size_t push( retired_ptr_node& node ) CDS_NOEXCEPT
@@ -331,7 +328,6 @@ namespace cds { namespace gc {
                 cds::details::Allocator< block, Alloc > m_BlockAllocator    ;   ///< block allocator
 
             private:
-                //@cond
                 void allocNewBlock()
                 {
                     // allocate new block
@@ -372,10 +368,8 @@ namespace cds { namespace gc {
                 {
                     return (m_nCurEpoch.load(atomics::memory_order_acquire) - 1) & (c_nEpochCount - 1);
                 }
-                //@endcond
 
             public:
-                //@cond
                 retired_ptr_pool()
                     : m_pBlockListHead( nullptr )
                     , m_nCurEpoch(0)
@@ -402,8 +396,6 @@ namespace cds { namespace gc {
                     m_nCurEpoch.fetch_add( 1, atomics::memory_order_acq_rel );
                 }
 
-                //@endcond
-
                 /// Allocates new retired pointer
                 retired_ptr_node&  alloc()
                 {
@@ -503,13 +495,11 @@ namespace cds { namespace gc {
                     return p;
                 }
 
-                //@cond
                 std::nullptr_t operator=(std::nullptr_t) CDS_NOEXCEPT
                 {
                     clear();
                     return nullptr;
                 }
-                //@endcond
 
             public: // for ThreadGC.
                 /*
@@ -547,10 +537,8 @@ namespace cds { namespace gc {
         */
         class Guard: public details::guard
         {
-            //@cond
             typedef details::guard    base_class;
             friend class ThreadGC;
-            //@endcond
 
             ThreadGC&    m_gc    ;    ///< ThreadGC object of current thread
         public:
@@ -573,12 +561,10 @@ namespace cds { namespace gc {
                 return base_class::operator =<T>( p );
             }
 
-            //@cond
             std::nullptr_t operator=(std::nullptr_t) CDS_NOEXCEPT
             {
                 return base_class::operator =(nullptr);
             }
-            //@endcond
         };
 
         /// Array of guards
@@ -666,7 +652,6 @@ namespace cds { namespace gc {
         class CDS_EXPORT_API GarbageCollector
         {
         private:
-            //@cond
             friend class ThreadGC;
 
             /// Internal GC statistics
@@ -680,7 +665,6 @@ namespace cds { namespace gc {
                     , m_nFreeGuardCount(0)
                 {}
             };
-            //@endcond
 
         public:
             /// Exception "No GarbageCollector object is created"
@@ -692,7 +676,6 @@ namespace cds { namespace gc {
                 size_t m_nGuardCount       ;   ///< Total guard count
                 size_t m_nFreeGuardCount   ;   ///< Count of free guard
 
-                //@cond
                 InternalState()
                     : m_nGuardCount(0)
                     , m_nFreeGuardCount(0)
@@ -705,7 +688,6 @@ namespace cds { namespace gc {
 
                     return *this;
                 }
-                //@endcond
             };
 
         private:
@@ -844,10 +826,8 @@ namespace cds { namespace gc {
             }
 
         private:
-            //@cond none
             GarbageCollector( size_t nLiberateThreshold, size_t nInitialThreadGuardCount );
             ~GarbageCollector();
-            //@endcond
         };
 
         /// Thread GC
@@ -975,13 +955,10 @@ namespace cds { namespace gc {
                 m_gc.retirePtr( p, pFunc );
             }
 
-            //@cond
             void scan()
             {
                 m_gc.scan();
             }
-            //@endcond
-
         };
 
         //////////////////////////////////////////////////////////
@@ -1011,6 +988,7 @@ namespace cds { namespace gc {
 
     }   // namespace dhp
 }}  // namespace cds::gc
+//@endcond
 
 #if CDS_COMPILER == CDS_COMPILER_MSVC
 #   pragma warning(pop)
diff --git a/cds/gc/details/hp.h b/cds/gc/details/hp.h
index 0e9f0c0d..88b56fa7 100644
--- a/cds/gc/details/hp.h
+++ b/cds/gc/details/hp.h
@@ -27,6 +27,7 @@
         2010.01.27  khizmax Introducing memory order constraint
 */
 
+//@cond
 namespace cds {
     /**
         @page cds_garbage_collectors_comparison GC comparison
@@ -286,7 +287,6 @@ namespace cds {
                 atomics::atomic<OS::ThreadId>    m_idOwner   ; ///< Owner thread id; 0 - the record is free (not owned)
                 atomics::atomic<bool>            m_bFree     ; ///< true if record if free (not owned)
 
-                //@cond
                 hplist_node( const GarbageCollector& HzpMgr )
                     : hp_record( HzpMgr ),
                     m_pNextNode( nullptr ),
@@ -299,7 +299,6 @@ namespace cds {
                     assert( m_idOwner.load( atomics::memory_order_relaxed ) == OS::c_NullThreadId );
                     assert( m_bFree.load(atomics::memory_order_relaxed) );
                 }
-                //@endcond
             };
 
             atomics::atomic<hplist_node *>   m_pListHead  ;  ///< Head of GC list
@@ -342,9 +341,7 @@ namespace cds {
             */
             void                DeletePtr( details::retired_ptr& p );
 
-            //@cond
             void detachAllThread();
-            //@endcond
 
         public:
             /// Creates GarbageCollector singleton
@@ -646,13 +643,11 @@ namespace cds {
                 }
             }
 
-            //@cond
             void scan()
             {
                 m_HzpManager.Scan( m_pHzpRec );
                 m_HzpManager.HelpScan( m_pHzpRec );
             }
-            //@endcond
         };
 
         /// Auto hp_guard.
@@ -663,13 +658,12 @@ namespace cds {
         */
         class guard
         {
-            //@cond
             details::hp_guard&   m_hp    ; ///< Hazard pointer guarded
             ThreadGC&           m_gc    ; ///< Thread GC
-            //@endcond
 
         public:
             typedef details::hp_guard::hazard_ptr hazard_ptr ;  ///< Hazard pointer type
+
         public:
             /// Allocates HP guard from \p gc
             guard( ThreadGC& gc )
@@ -705,7 +699,6 @@ namespace cds {
                 return m_hp = p;
             }
 
-            //@cond
             std::nullptr_t operator =(std::nullptr_t)
             {
                 return m_hp = nullptr;
@@ -715,7 +708,6 @@ namespace cds {
             {
                 return m_hp;
             }
-            //@endcond
         };
 
         /// Auto-managed array of hazard pointers
@@ -755,6 +747,7 @@ namespace cds {
 
     }   // namespace hp
 }}  // namespace cds::gc
+//@endcond
 
 // Inlines
 #include <cds/gc/details/hp_inline.h>
diff --git a/cds/gc/details/hp_alloc.h b/cds/gc/details/hp_alloc.h
index e057e1ba..de409bcf 100644
--- a/cds/gc/details/hp_alloc.h
+++ b/cds/gc/details/hp_alloc.h
@@ -27,14 +27,10 @@ namespace cds {
         public:
             typedef hazard_pointer   hazard_ptr;    ///< Hazard pointer type
         private:
-            //@cond
             typedef atomics::atomic<hazard_ptr>  base_class;
-            //@endcond
 
         protected:
-            //@cond
             template <class Allocator> friend class hp_allocator;
-            //@endcond
 
         public:
             hp_guard() CDS_NOEXCEPT
@@ -55,13 +51,11 @@ namespace cds {
                 return p;
             }
 
-            //@cond
             std::nullptr_t operator=(std::nullptr_t) CDS_NOEXCEPT
             {
                 clear();
                 return nullptr;
             }
-            //@endcond
 
             /// Returns current value of hazard pointer
             /**
@@ -126,10 +120,8 @@ namespace cds {
             static CDS_CONSTEXPR const size_t c_nCapacity = Count ;   ///< Capacity of the array
 
         private:
-            //@cond
             atomic_hazard_ptr *     m_arr               ;   ///< Hazard pointer array of size = \p Count
             template <class Allocator> friend class hp_allocator;
-            //@endcond
 
         public:
             /// Constructs uninitialized array.
@@ -197,15 +189,12 @@ namespace cds {
             typedef Allocator       allocator_type;     ///< allocator type
 
         private:
-            //@cond
             typedef cds::details::Allocator< atomic_hazard_ptr, allocator_type > allocator_impl;
 
             atomic_hazard_ptr * m_arrHazardPtr  ;   ///< Array of hazard pointers
             size_t              m_nTop          ;   ///< The top of stack
             const size_t        m_nCapacity     ;   ///< Array capacity
 
-            //@endcond
-
         public:
             /// Default ctor
             explicit hp_allocator(
@@ -298,7 +287,6 @@ namespace cds {
             }
 
         private:
-            //@cond
             void make_free() CDS_NOEXCEPT
             {
                 for ( size_t i = 0; i < capacity(); ++i )
@@ -310,7 +298,6 @@ namespace cds {
             {
                 return allocator_impl().NewArray( nCapacity );
             }
-            //@endcond
         };
 
     }}} // namespace gc::hp::details
diff --git a/cds/gc/details/hp_inline.h b/cds/gc/details/hp_inline.h
index 86bc997c..e4e22a8d 100644
--- a/cds/gc/details/hp_inline.h
+++ b/cds/gc/details/hp_inline.h
@@ -3,6 +3,7 @@
 #ifndef __CDS_GC_DETAILS_HP_INLINE_H
 #define __CDS_GC_DETAILS_HP_INLINE_H
 
+//@cond
 namespace cds {
     namespace gc{ namespace hp { namespace details {
 
@@ -19,8 +20,8 @@ namespace cds {
             m_arrRetired( HzpMgr )
         {}
 
-    } } }    // namespace gc::hp::details
+    }}}    // namespace gc::hp::details
 }    // namespace cds
-
+//@endcond
 
 #endif // #ifndef __CDS_GC_DETAILS_HP_INLINE_H
diff --git a/cds/gc/details/hp_type.h b/cds/gc/details/hp_type.h
index 21671216..27d2dd0d 100644
--- a/cds/gc/details/hp_type.h
+++ b/cds/gc/details/hp_type.h
@@ -5,6 +5,7 @@
 
 #include <cds/gc/details/retired_ptr.h> // free_retired_ptr_func
 
+//@cond
 namespace cds {
     namespace gc {
         namespace hp {
@@ -17,6 +18,7 @@ namespace cds {
         }
     }
 }
+//@endcond
 
 #endif // #ifndef __CDS_GC_DETAILS_HP_TYPE_H
 
diff --git a/cds/gc/impl/dhp_decl.h b/cds/gc/impl/dhp_decl.h
index 9c26fd87..0f31ce31 100644
--- a/cds/gc/impl/dhp_decl.h
+++ b/cds/gc/impl/dhp_decl.h
@@ -1,7 +1,7 @@
 //$$CDS-header$$
 
-#ifndef __CDS_GC_DHP_DHP_DECL_H
-#define __CDS_GC_DHP_DHP_DECL_H
+#ifndef __CDS_GC_IMPL_DHP_DECL_H
+#define __CDS_GC_IMPL_DHP_DECL_H
 
 #include <cds/gc/details/dhp.h>
 #include <cds/details/marked_ptr.h>
@@ -447,4 +447,4 @@ namespace cds { namespace gc {
 
 }} // namespace cds::gc
 
-#endif // #ifndef __CDS_GC_DHP_DHP_DECL_H
+#endif // #ifndef __CDS_GC_IMPL_DHP_DECL_H
diff --git a/cds/gc/impl/dhp_impl.h b/cds/gc/impl/dhp_impl.h
index 10b15f8e..834330b8 100644
--- a/cds/gc/impl/dhp_impl.h
+++ b/cds/gc/impl/dhp_impl.h
@@ -1,7 +1,7 @@
 //$$CDS-header$$
 
-#ifndef __CDS_GC_DHP_DHP_IMPL_H
-#define __CDS_GC_DHP_DHP_IMPL_H
+#ifndef __CDS_GC_IMPL_DHP_IMPL_H
+#define __CDS_GC_IMPL_DHP_IMPL_H
 
 #include <cds/threading/model.h>
 
@@ -40,4 +40,4 @@ namespace cds { namespace gc {
 }} // namespace cds::gc
 //@endcond
 
-#endif // #ifndef __CDS_GC_DHP_DHP_IMPL_H
+#endif // #ifndef __CDS_GC_IMPL_DHP_IMPL_H
diff --git a/cds/gc/impl/hp_decl.h b/cds/gc/impl/hp_decl.h
index 2beb88af..2524ddb9 100644
--- a/cds/gc/impl/hp_decl.h
+++ b/cds/gc/impl/hp_decl.h
@@ -1,7 +1,7 @@
 //$$CDS-header$$
 
-#ifndef __CDS_GC_HP_HP_DECL_H
-#define __CDS_GC_HP_HP_DECL_H
+#ifndef __CDS_GC_IMPL_HP_DECL_H
+#define __CDS_GC_IMPL_HP_DECL_H
 
 #include <stdexcept>    // overflow_error
 #include <cds/gc/details/hp.h>
@@ -360,6 +360,11 @@ namespace cds { namespace gc {
         };
 
     public:
+        /// \p scan() type
+        enum class scan_type {
+            classic = hp::classic,    ///< classic scan as described in Michael's papers
+            inplace = hp::inplace     ///< inplace scan without allocation
+        };
         /// Initializes hp::GarbageCollector singleton
         /**
             The constructor initializes GC singleton with passed parameters.
@@ -378,14 +383,14 @@ namespace cds { namespace gc {
             size_t nHazardPtrCount = 0,     ///< Hazard pointer count per thread
             size_t nMaxThreadCount = 0,     ///< Max count of simultaneous working thread in your application
             size_t nMaxRetiredPtrCount = 0, ///< Capacity of the array of retired objects for the thread
-            hp::scan_type nScanType = hp::inplace   ///< Scan type (see \ref hp::scan_type enum)
+            scan_type nScanType = scan_type::inplace   ///< Scan type (see \p scan_type enum)
         )
         {
             hp::GarbageCollector::Construct(
                 nHazardPtrCount,
                 nMaxThreadCount,
                 nMaxRetiredPtrCount,
-                nScanType
+                static_cast<hp::scan_type>(nScanType)
             );
         }
 
@@ -494,17 +499,17 @@ namespace cds { namespace gc {
         static void retire( T * p ) ;   // inline in hp_impl.h
 
         /// Get current scan strategy
-        hp::scan_type getScanType() const
+        scan_type getScanType() const
         {
-            return hp::GarbageCollector::instance().getScanType();
+            return static_cast<scan_type>( hp::GarbageCollector::instance().getScanType());
         }
 
         /// Set current scan strategy
         void setScanType(
-            hp::scan_type nScanType     ///< new scan strategy
+            scan_type nScanType     ///< new scan strategy
         )
         {
-            hp::GarbageCollector::instance().setScanType( nScanType );
+            hp::GarbageCollector::instance().setScanType( static_cast<hp::scan_type>(nScanType) );
         }
 
         /// Checks if Hazard Pointer GC is constructed and may be used
@@ -513,7 +518,6 @@ namespace cds { namespace gc {
             return hp::GarbageCollector::isUsed();
         }
 
-
         /// Forced GC cycle call for current thread
         /**
             Usually, this function should not be called directly.
@@ -528,4 +532,4 @@ namespace cds { namespace gc {
     };
 }}  // namespace cds::gc
 
-#endif  // #ifndef __CDS_GC_HP_HP_DECL_H
+#endif  // #ifndef __CDS_GC_IMPL_HP_DECL_H
diff --git a/cds/gc/impl/hp_impl.h b/cds/gc/impl/hp_impl.h
index 8d046e30..ccabd381 100644
--- a/cds/gc/impl/hp_impl.h
+++ b/cds/gc/impl/hp_impl.h
@@ -1,7 +1,7 @@
 //$$CDS-header$$
 
-#ifndef __CDS_GC_HP_HP_IMPL_H
-#define __CDS_GC_HP_HP_IMPL_H
+#ifndef __CDS_GC_IMPL_HP_IMPL_H
+#define __CDS_GC_IMPL_HP_IMPL_H
 
 #include <cds/threading/model.h>
 #include <cds/details/static_functor.h>
@@ -54,4 +54,4 @@ namespace cds { namespace gc {
 }} // namespace cds::gc
 //@endcond
 
-#endif // #ifndef __CDS_GC_HP_HP_IMPL_H
+#endif // #ifndef __CDS_GC_IMPL_HP_IMPL_H