2 This file is a part of libcds - Concurrent Data Structures library
4 (C) Copyright Maxim Khizhinsky (libcds.dev@gmail.com) 2006-2016
6 Source code repo: http://github.com/khizmax/libcds/
7 Download: http://sourceforge.net/projects/libcds/files/
9 Redistribution and use in source and binary forms, with or without
10 modification, are permitted provided that the following conditions are met:
12 * Redistributions of source code must retain the above copyright notice, this
13 list of conditions and the following disclaimer.
15 * Redistributions in binary form must reproduce the above copyright notice,
16 this list of conditions and the following disclaimer in the documentation
17 and/or other materials provided with the distribution.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #ifndef CDSLIB_GC_DETAILS_HP_H
32 #define CDSLIB_GC_DETAILS_HP_H
34 #include <cds/algo/atomic.h>
35 #include <cds/os/thread.h>
36 #include <cds/details/bounded_array.h>
37 #include <cds/user_setup/cache_line.h>
39 #include <cds/gc/details/hp_type.h>
40 #include <cds/gc/details/hp_alloc.h>
42 #if CDS_COMPILER == CDS_COMPILER_MSVC
43 # pragma warning(push)
44 // warning C4251: 'cds::gc::hp::GarbageCollector::m_pListHead' : class 'cds::cxx11_atomic::atomic<T>'
45 // needs to have dll-interface to be used by clients of class 'cds::gc::hp::GarbageCollector'
46 # pragma warning(disable: 4251)
51 2007.12.24 khizmax Add statistics and CDS_GATHER_HAZARDPTR_STAT macro
52 2008.03.06 khizmax Refactoring: implementation of HazardPtrMgr is moved to hazardptr.cpp
53 2008.03.08 khizmax Remove HazardPtrMgr singleton. Now you must initialize/destroy HazardPtrMgr calling
54 HazardPtrMgr::Construct / HazardPtrMgr::Destruct before use (usually in main() function).
55 2008.12.06 khizmax Refactoring. Changes class name, namespace hierarchy, all helper defs have been moved to details namespace
56 2010.01.27 khizmax Introducing memory order constraint
61 /// Different safe memory reclamation schemas (garbage collectors)
62 /** @ingroup cds_garbage_collector
64 This namespace specifies different safe memory reclamation (SMR) algorithms.
65 See \ref cds_garbage_collector "Garbage collectors"
69 /// Michael's Hazard Pointers reclamation schema
72 - [2002] Maged M.Michael "Safe memory reclamation for dynamic lock-freeobjects using atomic reads and writes"
73 - [2003] Maged M.Michael "Hazard Pointers: Safe memory reclamation for lock-free objects"
74 - [2004] Andrei Alexandrescy, Maged Michael "Lock-free Data Structures with Hazard Pointers"
76 The \p cds::gc::hp namespace and its members are internal representation of Hazard Pointer GC and should not be used directly.
77 Use \p cds::gc::HP class in your code.
79 Hazard Pointer garbage collector is a singleton. The main user-level part of Hazard Pointer schema is
80 GC class and its nested classes. Before use any HP-related class you must initialize HP garbage collector
81 by contructing \p cds::gc::HP object in beginning of your \p main().
82 See \p cds::gc::HP class for explanation.
87 class GarbageCollector;
93 typedef cds::gc::details::retired_ptr retired_ptr;
95 /// Array of retired pointers
97 The vector of retired pointer ready to delete.
99 The Hazard Pointer schema is build on thread-static arrays. For each HP-enabled thread the HP manager allocates
100 array of retired pointers. The array belongs to the thread: owner thread writes to the array, other threads
103 class retired_vector {
104 /// Underlying vector implementation
105 typedef cds::details::bounded_array<retired_ptr> retired_vector_impl;
107 retired_vector_impl m_arr ; ///< the array of retired pointers
108 size_t m_nSize ; ///< Current size of \p m_arr
112 typedef retired_vector_impl::iterator iterator;
115 explicit retired_vector( const cds::gc::hp::GarbageCollector& HzpMgr ); // inline
121 The capacity is constant for any thread. It is defined by cds::gc::hp::GarbageCollector.
123 size_t capacity() const CDS_NOEXCEPT
125 return m_arr.capacity();
128 /// Current vector size (count of retired pointers in the vector)
129 size_t size() const CDS_NOEXCEPT
134 /// Set vector size. Uses internally
135 void size( size_t nSize )
137 assert( nSize <= capacity());
141 /// Pushes retired pointer to the vector
142 void push( retired_ptr const& p )
144 assert( m_nSize < capacity());
145 m_arr[ m_nSize ] = p;
149 /// Checks if the vector is full (size() == capacity())
150 bool isFull() const CDS_NOEXCEPT
152 return m_nSize >= capacity();
156 iterator begin() CDS_NOEXCEPT
158 return m_arr.begin();
162 iterator end() CDS_NOEXCEPT
164 return m_arr.begin() + m_nSize;
167 /// Clears the vector. After clearing, size() == 0
168 void clear() CDS_NOEXCEPT
174 /// Hazard pointer record of the thread
176 The structure of type "single writer - multiple reader": only the owner thread may write to this structure
177 other threads have read-only access.
180 hp_allocator<> m_hzp; ///< array of hazard pointers. Implicit \ref CDS_DEFAULT_ALLOCATOR dependency
181 retired_vector m_arrRetired ; ///< Retired pointer array
183 char padding[cds::c_nCacheLineSize];
184 atomics::atomic<unsigned int> m_nSync; ///< dummy var to introduce synchronizes-with relationship between threads
185 char padding2[cds::c_nCacheLineSize];
188 explicit hp_record( const cds::gc::hp::GarbageCollector& HzpMgr ); // inline
192 /// Clears all hazard pointers
200 m_nSync.fetch_add( 1, atomics::memory_order_acq_rel );
203 } // namespace details
205 /// GarbageCollector::Scan phase strategy
207 See GarbageCollector::Scan for explanation
210 classic, ///< classic scan as described in Michael's works (see GarbageCollector::classic_scan)
211 inplace ///< inplace scan without allocation (see GarbageCollector::inplace_scan)
214 /// Hazard Pointer singleton
216 Safe memory reclamation schema by Michael "Hazard Pointers"
219 \li [2002] Maged M.Michael "Safe memory reclamation for dynamic lock-freeobjects using atomic reads and writes"
220 \li [2003] Maged M.Michael "Hazard Pointers: Safe memory reclamation for lock-free objects"
221 \li [2004] Andrei Alexandrescy, Maged Michael "Lock-free Data Structures with Hazard Pointers"
224 class CDS_EXPORT_API GarbageCollector
227 typedef cds::atomicity::event_counter event_counter ; ///< event counter type
229 /// Internal GC statistics
230 struct InternalState {
231 size_t nHPCount ; ///< HP count per thread (const)
232 size_t nMaxThreadCount ; ///< Max thread count (const)
233 size_t nMaxRetiredPtrCount ; ///< Max retired pointer count per thread (const)
234 size_t nHPRecSize ; ///< Size of HP record, bytes (const)
236 size_t nHPRecAllocated ; ///< Count of HP record allocations
237 size_t nHPRecUsed ; ///< Count of HP record used
238 size_t nTotalRetiredPtrCount ; ///< Current total count of retired pointers
239 size_t nRetiredPtrInFreeHPRecs ; ///< Count of retired pointer in free (unused) HP records
241 event_counter::value_type evcAllocHPRec ; ///< Count of \p hp_record allocations
242 event_counter::value_type evcRetireHPRec ; ///< Count of \p hp_record retire events
243 event_counter::value_type evcAllocNewHPRec; ///< Count of new \p hp_record allocations from heap
244 event_counter::value_type evcDeleteHPRec ; ///< Count of \p hp_record deletions
246 event_counter::value_type evcScanCall ; ///< Count of Scan calling
247 event_counter::value_type evcHelpScanCall ; ///< Count of HelpScan calling
248 event_counter::value_type evcScanFromHelpScan;///< Count of Scan calls from HelpScan
250 event_counter::value_type evcDeletedNode ; ///< Count of deleting of retired objects
251 event_counter::value_type evcDeferredNode ; ///< Count of objects that cannot be deleted in Scan phase because of a hazard_pointer guards it
254 /// No GarbageCollector object is created
255 class not_initialized : public std::runtime_error
260 : std::runtime_error( "Global Hazard Pointer GarbageCollector is not initialized" )
265 /// Not enough Hazard Pointer
266 class too_many_hazard_ptr : public std::length_error
270 too_many_hazard_ptr()
271 : std::length_error( "Not enough Hazard Pointer" )
277 /// Internal GC statistics
279 event_counter m_AllocHPRec ; ///< Count of \p hp_record allocations
280 event_counter m_RetireHPRec ; ///< Count of \p hp_record retire events
281 event_counter m_AllocNewHPRec ; ///< Count of new \p hp_record allocations from heap
282 event_counter m_DeleteHPRec ; ///< Count of \p hp_record deletions
284 event_counter m_ScanCallCount ; ///< Count of Scan calling
285 event_counter m_HelpScanCallCount ; ///< Count of HelpScan calling
286 event_counter m_CallScanFromHelpScan ; ///< Count of Scan calls from HelpScan
288 event_counter m_DeletedNode ; ///< Count of retired objects deleting
289 event_counter m_DeferredNode ; ///< Count of objects that cannot be deleted in Scan phase because of a hazard_pointer guards it
292 /// Internal list of cds::gc::hp::details::hp_record
293 struct hplist_node : public details::hp_record
295 atomics::atomic<hplist_node*> m_pNextNode; ///< next hazard ptr record in list
296 atomics::atomic<OS::ThreadId> m_idOwner; ///< Owner thread id; 0 - the record is free (not owned)
297 atomics::atomic<bool> m_bFree; ///< true if record is free (not owned)
300 explicit hplist_node( const GarbageCollector& HzpMgr )
301 : hp_record( HzpMgr ),
302 m_pNextNode( nullptr ),
303 m_idOwner( OS::c_NullThreadId ),
307 hplist_node( const GarbageCollector& HzpMgr, OS::ThreadId owner )
308 : hp_record( HzpMgr ),
309 m_pNextNode( nullptr ),
316 assert( m_idOwner.load( atomics::memory_order_relaxed ) == OS::c_NullThreadId );
317 assert( m_bFree.load(atomics::memory_order_relaxed));
322 atomics::atomic<hplist_node *> m_pListHead ; ///< Head of GC list
324 static GarbageCollector * m_pHZPManager ; ///< GC instance pointer
326 Statistics m_Stat ; ///< Internal statistics
327 bool m_bStatEnabled ; ///< true - statistics enabled
329 const size_t m_nHazardPointerCount ; ///< max count of thread's hazard pointer
330 const size_t m_nMaxThreadCount ; ///< max count of thread
331 const size_t m_nMaxRetiredPtrCount ; ///< max count of retired ptr per thread
332 scan_type m_nScanType ; ///< scan type (see \ref scan_type enum)
338 size_t nHazardPtrCount = 0, ///< Hazard pointer count per thread
339 size_t nMaxThreadCount = 0, ///< Max count of thread
340 size_t nMaxRetiredPtrCount = 0, ///< Capacity of the array of retired objects
341 scan_type nScanType = inplace ///< Scan type (see \ref scan_type enum)
347 /// Allocate new HP record
348 hplist_node * NewHPRec( OS::ThreadId owner );
350 /// Permanently deletes HPrecord \p pNode
352 Caveat: for performance reason this function is defined as inline and cannot be called directly
354 void DeleteHPRec( hplist_node * pNode );
356 void detachAllThread();
359 /// Creates GarbageCollector singleton
361 GC is the singleton. If GC instance is not exist then the function creates the instance.
362 Otherwise it does nothing.
364 The Michael's HP reclamation schema depends of three parameters:
366 \p nHazardPtrCount - HP pointer count per thread. Usually it is small number (2-4) depending from
367 the data structure algorithms. By default, if \p nHazardPtrCount = 0,
368 the function uses maximum of HP count for CDS library.
370 \p nMaxThreadCount - max count of thread with using HP GC in your application. Default is 100.
372 \p nMaxRetiredPtrCount - capacity of array of retired pointers for each thread. Must be greater than
373 \p nHazardPtrCount * \p nMaxThreadCount.
374 Default is 2 * \p nHazardPtrCount * \p nMaxThreadCount.
376 static void CDS_STDCALL Construct(
377 size_t nHazardPtrCount = 0, ///< Hazard pointer count per thread
378 size_t nMaxThreadCount = 0, ///< Max count of simultaneous working thread in your application
379 size_t nMaxRetiredPtrCount = 0, ///< Capacity of the array of retired objects for the thread
380 scan_type nScanType = inplace ///< Scan type (see \ref scan_type enum)
383 /// Destroys global instance of GarbageCollector
385 The parameter \p bDetachAll should be used carefully: if its value is \p true,
386 then the destroying GC automatically detaches all attached threads. This feature
387 can be useful when you have no control over the thread termination, for example,
388 when \p libcds is injected into existing external thread.
390 static void CDS_STDCALL Destruct(
391 bool bDetachAll = false ///< Detach all threads
394 /// Returns pointer to GarbageCollector instance
395 static GarbageCollector& instance()
397 if ( !m_pHZPManager )
398 throw not_initialized();
399 return *m_pHZPManager;
402 /// Checks if global GC object is constructed and may be used
403 static bool isUsed() CDS_NOEXCEPT
405 return m_pHZPManager != nullptr;
408 /// Returns max Hazard Pointer count defined in construction time
409 size_t getHazardPointerCount() const CDS_NOEXCEPT
411 return m_nHazardPointerCount;
414 /// Returns max thread count defined in construction time
415 size_t getMaxThreadCount() const CDS_NOEXCEPT
417 return m_nMaxThreadCount;
420 /// Returns max size of retired objects array. It is defined in construction time
421 size_t getMaxRetiredPtrCount() const CDS_NOEXCEPT
423 return m_nMaxRetiredPtrCount;
426 // Internal statistics
428 /// Get internal statistics
429 InternalState& getInternalState(InternalState& stat) const;
431 /// Checks if internal statistics enabled
432 bool isStatisticsEnabled() const { return m_bStatEnabled; }
434 /// Enables/disables internal statistics
435 bool enableStatistics( bool bEnable )
437 bool bEnabled = m_bStatEnabled;
438 m_bStatEnabled = bEnable;
442 /// Checks that required hazard pointer count \p nRequiredCount is less or equal then max hazard pointer count
444 If \p nRequiredCount > getHazardPointerCount() then the exception \p too_many_hazard_ptr is thrown
446 static void checkHPCount( unsigned int nRequiredCount )
448 if ( instance().getHazardPointerCount() < nRequiredCount )
449 throw too_many_hazard_ptr();
452 /// Get current scan strategy
453 scan_type getScanType() const
458 /// Set current scan strategy
459 /** @anchor hzp_gc_setScanType
460 Scan strategy changing is allowed on the fly.
463 scan_type nScanType ///< new scan strategy
466 m_nScanType = nScanType;
469 public: // Internals for threads
471 /// Allocates Hazard Pointer GC record. For internal use only
472 details::hp_record* alloc_hp_record();
474 /// Free HP record. For internal use only
475 void free_hp_record( details::hp_record* pRec );
477 /// The main garbage collecting function
479 This function is called internally by ThreadGC object when upper bound of thread's list of reclaimed pointers
482 There are the following scan algorithm:
483 - \ref hzp_gc_classic_scan "classic_scan" allocates memory for internal use
484 - \ref hzp_gc_inplace_scan "inplace_scan" does not allocate any memory
486 Use \ref hzp_gc_setScanType "setScanType" member function to setup appropriate scan algorithm.
488 void Scan( details::hp_record * pRec )
490 switch ( m_nScanType ) {
492 inplace_scan( pRec );
495 assert(false) ; // Forgotten something?..
497 classic_scan( pRec );
502 /// Helper scan routine
504 The function guarantees that every node that is eligible for reuse is eventually freed, barring
505 thread failures. To do so, after executing Scan, a thread executes a HelpScan,
506 where it checks every HP record. If an HP record is inactive, the thread moves all "lost" reclaimed pointers
507 to thread's list of reclaimed pointers.
509 The function is called internally by Scan.
511 void HelpScan( details::hp_record * pThis );
514 /// Classic scan algorithm
515 /** @anchor hzp_gc_classic_scan
516 Classical scan algorithm as described in Michael's paper.
518 A scan includes four stages. The first stage involves scanning the array HP for non-null values.
519 Whenever a non-null value is encountered, it is inserted in a local list of currently protected pointer.
520 Only stage 1 accesses shared variables. The following stages operate only on private variables.
522 The second stage of a scan involves sorting local list of protected pointers to allow
523 binary search in the third stage.
525 The third stage of a scan involves checking each reclaimed node
526 against the pointers in local list of protected pointers. If the binary search yields
527 no match, the node is freed. Otherwise, it cannot be deleted now and must kept in thread's list
528 of reclaimed pointers.
530 The forth stage prepares new thread's private list of reclaimed pointers
531 that could not be freed during the current scan, where they remain until the next scan.
533 This algorithm allocates memory for internal HP array.
535 This function is called internally by ThreadGC object when upper bound of thread's list of reclaimed pointers
538 void classic_scan( details::hp_record * pRec );
540 /// In-place scan algorithm
541 /** @anchor hzp_gc_inplace_scan
542 Unlike the \ref hzp_gc_classic_scan "classic_scan" algorithm, \p inplace_scan does not allocate any memory.
543 All operations are performed in-place.
545 void inplace_scan( details::hp_record * pRec );
548 /// Thread's hazard pointer manager
550 To use Hazard Pointer reclamation schema each thread object must be linked with the object of ThreadGC class
551 that interacts with GarbageCollector global object. The linkage is performed by calling \ref cds_threading "cds::threading::Manager::attachThread()"
552 on the start of each thread that uses HP GC. Before terminating the thread linked to HP GC it is necessary to call
553 \ref cds_threading "cds::threading::Manager::detachThread()".
557 GarbageCollector& m_HzpManager; ///< Hazard Pointer GC singleton
558 details::hp_record* m_pHzpRec; ///< Pointer to thread's HZP record
561 /// Default constructor
563 : m_HzpManager( GarbageCollector::instance()),
567 /// The object is not copy-constructible
568 ThreadGC( ThreadGC const& ) = delete;
575 /// Checks if thread GC is initialized
576 bool isInitialized() const { return m_pHzpRec != nullptr; }
578 /// Initialization. Repeat call is available
582 m_pHzpRec = m_HzpManager.alloc_hp_record();
585 /// Finalization. Repeat call is available
589 details::hp_record* pRec = m_pHzpRec;
591 m_HzpManager.free_hp_record( pRec );
595 /// Initializes HP guard \p guard
596 details::hp_guard* allocGuard()
599 return m_pHzpRec->m_hzp.alloc();
602 /// Frees HP guard \p guard
603 void freeGuard( details::hp_guard* guard )
606 m_pHzpRec->m_hzp.free( guard );
609 /// Initializes HP guard array \p arr
610 template <size_t Count>
611 size_t allocGuard( details::hp_array<Count>& arr )
614 return m_pHzpRec->m_hzp.alloc( arr );
617 /// Frees HP guard array \p arr
618 template <size_t Count>
619 void freeGuard( details::hp_array<Count>& arr )
622 m_pHzpRec->m_hzp.free( arr );
625 /// Places retired pointer \p and its deleter \p pFunc into thread's array of retired pointer for deferred reclamation
626 template <typename T>
627 void retirePtr( T * p, void (* pFunc)(T *))
629 retirePtr( details::retired_ptr( reinterpret_cast<void *>( p ), reinterpret_cast<free_retired_ptr_func>( pFunc )));
632 /// Places retired pointer \p into thread's array of retired pointer for deferred reclamation
633 void retirePtr( details::retired_ptr const& p )
635 m_pHzpRec->m_arrRetired.push( p );
637 if ( m_pHzpRec->m_arrRetired.isFull()) {
638 // Max of retired pointer count is reached. Do scan
643 /// Run retiring scan cycle
646 m_HzpManager.Scan( m_pHzpRec );
647 m_HzpManager.HelpScan( m_pHzpRec );
652 assert( m_pHzpRec != nullptr );
658 }} // namespace cds::gc
664 namespace gc { namespace hp { namespace details {
666 inline retired_vector::retired_vector( const cds::gc::hp::GarbageCollector& HzpMgr )
667 : m_arr( HzpMgr.getMaxRetiredPtrCount()),
671 inline hp_record::hp_record( const cds::gc::hp::GarbageCollector& HzpMgr )
672 : m_hzp( HzpMgr.getHazardPointerCount())
673 , m_arrRetired( HzpMgr )
677 }}} // namespace gc::hp::details
682 #if CDS_COMPILER == CDS_COMPILER_MSVC
683 # pragma warning(pop)
686 #endif // #ifndef CDSLIB_GC_DETAILS_HP_H