jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr Struct Reference

Reference-counted handle to a pooled object. More...

#include <jh/concurrent/flat_pool.h>

Public Member Functions
	ptr ()=default
	Default-constructs a null handle.
	ptr (flat_pool *p, size_t i)
	Constructs a handle referencing a pool slot.
	ptr (std::nullptr_t)
	Constructs a null handle.
	ptr (const ptr &o)
	Copy-constructs a handle.
ptr &	operator= (const ptr &o)
	Copy-assigns a handle.
	ptr (ptr &&o) noexcept
	Move-constructs a handle.
ptr &	operator= (ptr &&o) noexcept
	Move-assigns a handle.
	~ptr ()
	Releases the reference held by this handle.
void	reset ()
	Releases the reference held by this handle and resets it to null.
value_type &	operator* ()
	Dereferences the handle to access the stored object.
value_type *	operator-> ()
	Member access to the stored object.
bool	operator== (const ptr &other) const =default
	Compares two handles for equality.
bool	operator== (std::nullptr_t)
	Compares the handle against nullptr.
	operator bool () const noexcept
	Returns true if the handle is non-null.
flat_pool::no_reallocate_guard	guard () const
	Acquires a guard that prevents pool reallocation during dereference.

Detailed Description

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>
struct jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr

Reference-counted handle to a pooled object.

flat_pool::ptr is a lightweight RAII handle that represents a reference to a slot within a flat_pool.

Copying a ptr increments the underlying slot's reference count. Destruction or reset decrements it. When the count reaches zero, the slot becomes eligible for reuse.

Dereferencing and Safety

Dereferencing yields a reference or pointer to the underlying stored object. In multithreaded contexts where the pool may be resized concurrently, users must acquire a no_reallocate_guard before dereferencing to prevent vector reallocation.

Null Semantics

A default-constructed or explicitly reset ptr represents a null handle and compares equal to nullptr.

Note

In fact, flat_pool::ptr behaves exactly like shared_ptr (i.e., copy/move construction/assignment shares the handle, and the object is logically dead when the count is 0).
Even if the slot is not reused, the object remains unreachable once it is dead.
flat_pool::ptr, as a pool pointer, simply provides an additional way to retrieve objects from the pool using find and acquire, as well as lazy (GC-like) object destruction.

Constructor & Destructor Documentation

ptr() [1/3]

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::ptr ( flat_pool * p, size_t i )

inline

Constructs a handle referencing a pool slot.

Parameters

p	Pointer to the owning pool.
i	Storage index within the pool.

ptr() [2/3]

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::ptr ( const ptr & o )

inline

Copy-constructs a handle.

The new handle references the same slot and increments the associated reference count.

Parameters

o	Source handle.

ptr() [3/3]

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::ptr ( ptr && o )

inlinenoexcept

Move-constructs a handle.

Transfers the reference without modifying the reference count. The source handle is reset to null.

Parameters

o	Source handle.

~ptr()

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::~ptr ( )

inline

Releases the reference held by this handle.

If the reference count drops to zero, the slot is marked as unoccupied, but the stored object is not destroyed at this point.

This design avoids immediate destructor invocation, which may be expensive. In many cases, reassigning an existing object is cheaper than destroying and reconstructing it.

The underlying object is only destroyed when the slot is reused or forcibly reclaimed during resize_pool(), following a GC-like deferred reclamation strategy.

Member Function Documentation

guard()

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

flat_pool::no_reallocate_guard jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::guard ( ) const

inlinenodiscard

Acquires a guard that prevents pool reallocation during dereference.

The pointer itself is stable, but the underlying contiguous storage may be reallocated by other threads, which would invalidate any obtained T& or T*. This guard prevents such reallocation while it is held.

In multithreaded contexts, the guard must be held whenever dereferencing the pointer if other threads may trigger pool resizing.

Returns

A guard witch is non-copyable, non-movable, and scope-bound, making escape or misuse impossible.

operator*()

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

value_type & jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::operator* ( )

inline

Dereferences the handle to access the stored object.

In single-threaded usage, this operator may be used directly.

In multithreaded contexts, if more than one thread may operate on the pool and any operation could trigger reallocation (including insertion or resize_pool()), the caller must hold a guard obtained via auto g = p.guard(); for the duration of the access.

Failing to do so may result in a dangling reference even though the pointer itself remains logically valid.

operator->()

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

value_type * jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::operator-> ( )

inline

Member access to the stored object.

In single-threaded usage, this operator may be used directly.

In multithreaded contexts where concurrent operations on the pool may cause reallocation (such as insertion or forced shrinking), callers must acquire a guard with auto g = p.guard(); before using this operator.

The guard ensures the underlying storage remains stable for the duration of the access.

operator=() [1/2]

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

ptr & jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::operator= ( const ptr & o )

inline

Copy-assigns a handle.

Releases the currently held reference (if any), then acquires a reference to the slot held by the source handle.

Parameters

o	Source handle.

Returns

Reference to this handle.

operator=() [2/2]

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

ptr & jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::operator= ( ptr && o )

inlinenoexcept

Move-assigns a handle.

Releases the currently held reference (if any) and takes ownership of the reference held by the source handle. The source handle is reset to null.

Parameters

o	Source handle.

Returns

Reference to this handle.

reset()

template<typename Key, typename Value = jh::typed::monostate, typename Hash = jh::hash<Key>, typename Alloc = std::allocator<detail::value_t<Key, Value>>>

void jh::conc::flat_pool< Key, Value, Hash, Alloc >::ptr::reset ( )

inline

Releases the reference held by this handle and resets it to null.

This function follows STL smart pointer conventions: the handle is explicitly reset to a null state rather than being manually destroyed.

Decrements the reference count of the associated slot. If the count reaches zero, the slot is marked as unoccupied but the stored object is not immediately destroyed.

---

The documentation for this struct was generated from the following file:

• include/jh/concurrent/flat_pool.h