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

Protected Member Functions

 Counting_cap_alloc () throw ()
 Create a new, empty allocator. More...
 
void setup (void *m, long capacity, long bias) throw ()
 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 ( )
throw (
)
inlineprotected

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 ( )
throw (
)
inline

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.

◆ alloc() [2/2]

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

Allocate a new capability slot.

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

Definition at line 156 of file counting_cap_alloc.

◆ 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 
)
throw (
)
inline

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

◆ 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 
)
throw (
)
inline

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

◆ setup()

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

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)
throw (
)
inline

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


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