From a70b41b500887da4049b17ea5b2ca49d58de0442 Mon Sep 17 00:00:00 2001 From: khizmax Date: Thu, 18 Dec 2014 19:11:01 +0300 Subject: [PATCH] fix doc --- cds/gc/details/dhp.h | 3 +++ cds/gc/details/hp.h | 6 ++++++ cds/gc/hp.h | 7 +------ cds/gc/impl/dhp_decl.h | 26 +++++++++++++++++++------- cds/gc/impl/hp_decl.h | 8 +++++--- 5 files changed, 34 insertions(+), 16 deletions(-) diff --git a/cds/gc/details/dhp.h b/cds/gc/details/dhp.h index 142cabb8..58981ef9 100644 --- a/cds/gc/details/dhp.h +++ b/cds/gc/details/dhp.h @@ -702,6 +702,7 @@ 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) @@ -714,6 +715,7 @@ namespace cds { namespace gc { return *this; } + //@endcond }; private: @@ -986,6 +988,7 @@ namespace cds { namespace gc { m_gc.retirePtr( p, pFunc ); } + /// Run retiring cycle void scan() { m_gc.scan(); diff --git a/cds/gc/details/hp.h b/cds/gc/details/hp.h index d33b72fb..4555c48d 100644 --- a/cds/gc/details/hp.h +++ b/cds/gc/details/hp.h @@ -258,6 +258,7 @@ namespace cds { atomics::atomic m_idOwner; ///< Owner thread id; 0 - the record is free (not owned) atomics::atomic m_bFree; ///< true if record if free (not owned) + //@cond hplist_node( const GarbageCollector& HzpMgr ) : hp_record( HzpMgr ), m_pNextNode( nullptr ), @@ -270,6 +271,7 @@ namespace cds { assert( m_idOwner.load( atomics::memory_order_relaxed ) == OS::c_NullThreadId ); assert( m_bFree.load(atomics::memory_order_relaxed) ); } + //@endcond }; atomics::atomic m_pListHead ; ///< Head of GC list @@ -608,6 +610,7 @@ namespace cds { } } + /// Run retiring scan cycle void scan() { m_HzpManager.Scan( m_pHzpRec ); @@ -646,11 +649,14 @@ namespace cds { return m_hp = p; } + //@cond std::nullptr_t operator =(std::nullptr_t) { return m_hp = nullptr; } + //@endcond + /// Get raw guarded pointer hazard_ptr get() const { return m_hp; diff --git a/cds/gc/hp.h b/cds/gc/hp.h index 026cdd7b..93d05693 100644 --- a/cds/gc/hp.h +++ b/cds/gc/hp.h @@ -29,14 +29,9 @@ Array of retired pointers - preallocated for each thread, limited in size + preallocated for each thread, size is limited global for the entire process, unlimited (dynamically allocated when needed) - - Support direct pointer to item of lock-free container (useful for iterators) - not supported - not supported - 1Unbounded count of retired pointer means a possibility of memory exhaustion. diff --git a/cds/gc/impl/dhp_decl.h b/cds/gc/impl/dhp_decl.h index a3825f06..23f698f7 100644 --- a/cds/gc/impl/dhp_decl.h +++ b/cds/gc/impl/dhp_decl.h @@ -561,10 +561,20 @@ namespace cds { namespace gc { }; public: - /// Initializes dhp::GarbageCollector singleton + /// Initializes %DHP memory manager singleton /** - The constructor calls GarbageCollector::Construct with passed parameters. - See dhp::GarbageCollector::Construct for explanation of parameters meaning. + Constructor creates and initializes %DHP global object. + %DHP object should be created before using CDS data structure based on \p %cds::gc::DHP GC. Usually, + it is created in the \p main() function. + After creating of global object you may use CDS data structures based on \p %cds::gc::DHP. + + \par Parameters + - \p nLiberateThreshold - \p scan() threshold. When count of retired pointers reaches this value, + the \p scan() member function would be called for freeing retired pointers. + - \p nInitialThreadGuardCount - initial count of guard allocated for each thread. + When a thread is initialized the GC allocates local guard pool for the thread from common guard pool. + By perforce the local thread's guard pool is grown automatically from common pool. + When the thread terminated its guard pool is backed to common GC's pool. */ DHP( size_t nLiberateThreshold = 1024 @@ -577,9 +587,11 @@ namespace cds { namespace gc { ); } - /// Terminates dhp::GarbageCollector singleton + /// Destroys %DHP memory manager /** - The destructor calls \code dhp::GarbageCollector::Destruct() \endcode + The destructor destroys %DHP global object. After calling of this function you may \b NOT + use CDS data structures based on \p %cds::gc::DHP. + Usually, %DHP object is destroyed at the end of your \p main(). */ ~DHP() { @@ -589,7 +601,7 @@ namespace cds { namespace gc { /// Checks if count of hazard pointer is no less than \p nCountNeeded /** The function always returns \p true since the guard count is unlimited for - \p gc::DHP garbage collector. + \p %gc::DHP garbage collector. */ static CDS_CONSTEXPR bool check_available_guards( #ifdef CDS_DOXYGEN_INVOKED @@ -619,7 +631,7 @@ namespace cds { namespace gc { The function places pointer \p p to array of pointers ready for removing. (so called retired pointer array). The pointer can be safely removed when no guarded pointer points to it. - See gc::HP::retire for \p Disposer requirements. + See \p gc::HP::retire for \p Disposer requirements. */ template static void retire( T * p ) diff --git a/cds/gc/impl/hp_decl.h b/cds/gc/impl/hp_decl.h index e47ff0cf..b446e1a2 100644 --- a/cds/gc/impl/hp_decl.h +++ b/cds/gc/impl/hp_decl.h @@ -572,13 +572,13 @@ namespace cds { namespace gc { classic = hp::classic, ///< classic scan as described in Michael's papers inplace = hp::inplace ///< inplace scan without allocation }; - /// Initializes hp::GarbageCollector singleton + /// Initializes %HP singleton /** The constructor initializes GC singleton with passed parameters. If GC instance is not exist then the function creates the instance. Otherwise it does nothing. - The Michael's HP reclamation schema depends of three parameters: + The Michael's %HP reclamation schema depends of three parameters: - \p nHazardPtrCount - hazard pointer count per thread. Usually it is small number (up to 10) depending from the data structure algorithms. By default, if \p nHazardPtrCount = 0, the function uses maximum of the hazard pointer count for CDS library. @@ -603,7 +603,9 @@ namespace cds { namespace gc { /// Terminates GC singleton /** - The destructor calls \code hp::GarbageCollector::Destruct( true ) \endcode + The destructor destroys %HP global object. After calling of this function you may \b NOT + use CDS data structures based on \p %cds::gc::HP. + Usually, %HP object is destroyed at the end of your \p main(). */ ~HP() { -- 2.34.1