L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg > Class Template Reference

Internal reference-counting cap allocator. More...

#include <counting_cap_alloc>

Collaboration diagram for L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >:

Public Member Functions
L4::Cap< void >	alloc () noexcept
	Allocate a new capability slot.
template<typename T >
L4::Cap< T >	alloc () noexcept
	Allocate a new capability slot.
void	take (L4::Cap< void > cap) noexcept
	Increase the reference counter for the capability.
bool	free (L4::Cap< void > cap, l4_cap_idx_t task=L4_INVALID_CAP, unsigned unmap_flags=L4_FP_ALL_SPACES) noexcept
	Free the capability.
bool	release (L4::Cap< void > cap, l4_cap_idx_t task=L4_INVALID_CAP, unsigned unmap_flags=L4_FP_ALL_SPACES) noexcept
	Decrease the reference counter for a capability.
long	last () noexcept
	Return highest capability id managed by this allocator.

Protected Member Functions
	Counting_cap_alloc () noexcept
	Create a new, empty allocator.
void	setup (void *m, long capacity, long bias, Dbg *dbg) noexcept
	Set up the backing memory for the allocator and the area of managed capability slots.

Detailed Description

template<typename COUNTERTYPE, typename Dbg>
class L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >

Internal reference-counting cap allocator.

This is intended for internal use only. L4Re applications should use L4Re::Util::cap_alloc().

Allocator for capability slots that automatically frees the slot and optionally unmaps the capability when the reference count goes down to zero. Reference counting must be done manually via take() and release(). The backing store for the reference counters must be provided in the setup() method. The allocator can recognize capability slots that are not managed by itself and does nothing on such slots.

Note

The user must ensure that the backing store is zero-initialized.

The user must ensure that the capability slots managed by this allocator are not used by a different allocator, see setup().

The operations in this class are not thread-safe.

Definition at line 202 of file counting_cap_alloc.

Constructor & Destructor Documentation

Counting_cap_alloc()

template<typename COUNTERTYPE , typename Dbg >

L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::Counting_cap_alloc ( )

inlineprotectednoexcept

Create a new, empty allocator.

Needs to be initialized with setup() before it can be used.

Definition at line 231 of file counting_cap_alloc.

Member Function Documentation

alloc() [1/2]

template<typename COUNTERTYPE , typename Dbg >

L4::Cap< void > L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::alloc ( )

inlinenoexcept

Allocate a new capability slot.

Returns

The newly allocated capability slot, invalid if the allocator was exhausted.

Definition at line 269 of file counting_cap_alloc.

References L4_CAP_SHIFT.

Referenced by L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::alloc().

Here is the caller graph for this function:

alloc() [2/2]

template<typename COUNTERTYPE , typename Dbg >

template<typename T >

L4::Cap< T > L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::alloc ( )

inlinenoexcept

Allocate a new capability slot.

Returns

The newly allocated capability slot, invalid if the allocator was exhausted.

Definition at line 294 of file counting_cap_alloc.

References L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::alloc().

Here is the call graph for this function:

free()

template<typename COUNTERTYPE , typename Dbg >

bool L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::free ( L4::Cap< void >  cap, l4_cap_idx_t  task = L4_INVALID_CAP, unsigned  unmap_flags = L4_FP_ALL_SPACES  )

inlinenoexcept

Free the capability.

Parameters

cap	Capability to free.
task	If set, task to unmap the capability from.
unmap_flags	Flags for unmap, see l4_unmap_flags_t.

Precondition

The capability has been allocated. Calling free twice on a capability managed by this allocator results in undefined behaviour.

Returns

True, if the capability was managed by this allocator.

Definition at line 333 of file counting_cap_alloc.

References l4_assert, l4_is_valid_cap(), and l4_task_unmap().

Here is the call graph for this function:

release()

template<typename COUNTERTYPE , typename Dbg >

bool L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::release ( L4::Cap< void >  cap, l4_cap_idx_t  task = L4_INVALID_CAP, unsigned  unmap_flags = L4_FP_ALL_SPACES  )

inlinenoexcept

Decrease the reference counter for a capability.

Parameters

cap	Capability to release.
task	If set, task to unmap the capability from.
unmap_flags	Flags for unmap, see l4_unmap_flags_t.

Precondition

The capability has been allocated. Calling release on a free capability results in undefined behaviour.

Returns

True, if the capability was freed as a result of this operation. If false is returned the capability is either still in use or is not managed by this allocator.

Does nothing apart from returning false if the capability is not managed by this allocator.

Definition at line 371 of file counting_cap_alloc.

References l4_assert, L4_INVALID_CAP, and l4_task_unmap().

Here is the call graph for this function:

setup()

template<typename COUNTERTYPE , typename Dbg >

void L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::setup ( void *  m, long  capacity, long  bias, Dbg *  dbg  )

inlineprotectednoexcept

Set up the backing memory for the allocator and the area of managed capability slots.

Parameters

m	Pointer to backing memory.
capacity	Number of capabilities that can be stored.
bias	First capability id to use by this allocator.
dbg	Logger for warnings if counter got saturated.

The allocator will manage the capability slots between bias and bias + capacity - 1 (inclusive). It is the responsibility of the user to ensure that these slots are not used otherwise.

Definition at line 254 of file counting_cap_alloc.

take()

template<typename COUNTERTYPE , typename Dbg >

void L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::take ( L4::Cap< void >  cap )

inlinenoexcept

Increase the reference counter for the capability.

Parameters

cap	Capability, whose reference counter should be increased.

If the capability was still free, it will be automatically allocated. Silently does nothing if the capability is not managed by this allocator.

Definition at line 308 of file counting_cap_alloc.

References L4_CAP_SHIFT, and L4_UNLIKELY.

---

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

• l4/re/util/counting_cap_alloc