L4Re – L4 Runtime Environment
L4Re::Util::Counting_cap_alloc< COUNTERTYPE > Class Template Reference

Internal reference-counting cap allocator. More...

+ Collaboration diagram for L4Re::Util::Counting_cap_alloc< COUNTERTYPE >:

Public Member Functions

L4::Cap< void > alloc () noexcept
 Allocate a new capability slot. More...
 
template<typename T >
L4::Cap< T > alloc () noexcept
 Allocate a new capability slot. More...
 
void take (L4::Cap< void > cap) noexcept
 Increase the reference counter for the capability. More...
 
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. More...
 
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. More...
 
long last () noexcept
 Return highest capability id managed by this allocator.
 

Protected Member Functions

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

Detailed Description

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
class L4Re::Util::Counting_cap_alloc< COUNTERTYPE >

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 75 of file counting_cap_alloc.

Constructor & Destructor Documentation

◆ Counting_cap_alloc()

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::Counting_cap_alloc ( )
inlineprotectednoexcept

Create a new, empty allocator.

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

Definition at line 104 of file counting_cap_alloc.

Member Function Documentation

◆ alloc() [1/2]

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
L4::Cap<void> L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::alloc ( )
inlinenoexcept

Allocate a new capability slot.

Returns
The newly allocated capability slot, invalid if the allocator was exhausted.
Examples
examples/libs/l4re/c++/mem_alloc/ma+rm.cc, examples/libs/l4re/c++/shared_ds/ds_clnt.cc, and examples/libs/l4re/c++/shared_ds/ds_srv.cc.

Definition at line 135 of file counting_cap_alloc.

References L4_CAP_SHIFT.

Referenced by L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::alloc(), L4Re::Util::make_ref_cap(), L4Re::Util::make_ref_del_cap(), L4Re::Util::make_shared_cap(), L4Re::Util::make_shared_del_cap(), L4Re::Util::make_unique_cap(), and L4Re::Util::make_unique_del_cap().

+ Here is the caller graph for this function:

◆ alloc() [2/2]

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
template<typename T >
L4::Cap<T> L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::alloc ( )
inlinenoexcept

Allocate a new capability slot.

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

Definition at line 153 of file counting_cap_alloc.

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

+ Here is the call graph for this function:

◆ free()

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
bool L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::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
capCapability to free.
taskIf set, task to unmap the capability from.
unmap_flagsFlags 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.
Examples
examples/libs/l4re/c++/mem_alloc/ma+rm.cc, examples/libs/l4re/c++/shared_ds/ds_clnt.cc, examples/libs/l4re/c++/shared_ds/ds_srv.cc, and examples/libs/l4re/streammap/client.cc.

Definition at line 195 of file counting_cap_alloc.

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

Referenced by L4Re::Util::Smart_cap_auto< Unmap_flags >::free(), and L4Re::Util::Object_registry::unregister_obj().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ release()

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
bool L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::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
capCapability to release.
taskIf set, task to unmap the capability from.
unmap_flagsFlags 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 238 of file counting_cap_alloc.

References L4::dec, l4_assert, L4_CAP_SHIFT, L4_INVALID_CAP, and l4_task_unmap().

Referenced by L4Re::Util::Smart_count_cap< Unmap_flags >::free().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setup()

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
void L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::setup ( void *  m,
long  capacity,
long  bias 
)
inlineprotectednoexcept

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

Parameters
mPointer to backing memory.
capacityNumber of capabilities that can be stored.
biasFirst capability id to use by this allocator.

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 121 of file counting_cap_alloc.

◆ take()

template<typename COUNTERTYPE = L4Re::Util::Counter<unsigned char>>
void L4Re::Util::Counting_cap_alloc< COUNTERTYPE >::take ( L4::Cap< void >  cap)
inlinenoexcept

Increase the reference counter for the capability.

Parameters
capCapability, 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 168 of file counting_cap_alloc.

References L4_CAP_SHIFT.

Referenced by L4Re::Util::Smart_count_cap< Unmap_flags >::copy().

+ Here is the caller graph for this function:

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