Supports tracking instances which can come and go during runtime. More...

Collaboration diagram for Instance List:

Classes
struct	embutil::InstanceElem< TTrackedClass, TKey >
	Helper struct which is used to store Key/Value pairs in the InstanceList. More...

class	embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >
	Generic InstanceList template container. More...

Typedefs
template<class TTrackedClass , typename TKey = const char*, class TContainer = std::list<InstanceElem<TTrackedClass, TKey>>>
using	embutil::DynamicInstanceList = InstanceList< TTrackedClass, TKey, TContainer >
	Template class to track instances of class-type things (dynamic memory variant) More...

template<class TTrackedClass , const size_t TSize = 32, typename TKey = const char*, class TContainer = etl::list<InstanceElem<TTrackedClass, TKey>, TSize>>
using	embutil::StaticInstanceList = InstanceList< TTrackedClass, TKey, TContainer, TSize >
	Template class to track instances of class-type things (static memory variant) More...

Detailed Description

Supports tracking instances which can come and go during runtime.

Class Documentation

◆ embutil::InstanceElem

struct embutil::InstanceElem

template<class TTrackedClass, typename TKey>
struct embutil::InstanceElem< TTrackedClass, TKey >

Helper struct which is used to store Key/Value pairs in the InstanceList.

This structure respresents an Instance element. The key and value are stored in the element struct, and an operator==() is implemented to support the find() and find_if() functions.

Template Parameters

TTrackedClass	the type of class being tracked by the instance element.
TKey	the type of the key used to access the element.

Public Member Functions
bool	operator== (const InstanceElem &t) const noexcept
	Compare equality between two instance elements. More...

Public Attributes
TKey	key

TTrackedClass *	value

Member Function Documentation

◆ operator==()

template<class TTrackedClass , typename TKey >

bool embutil::InstanceElem< TTrackedClass, TKey >::operator== ( const InstanceElem< TTrackedClass, TKey > & t ) const

inlinenoexcept

Compare equality between two instance elements.

Both the key and the value must match for two instance elements to be equal.

References t.

Member Data Documentation

◆ key

template<class TTrackedClass , typename TKey >

TKey embutil::InstanceElem< TTrackedClass, TKey >::key

◆ value

template<class TTrackedClass , typename TKey >

TTrackedClass* embutil::InstanceElem< TTrackedClass, TKey >::value

◆ embutil::InstanceList

class embutil::InstanceList

template<class TTrackedClass, typename TKey, class TContainer, const size_t TSize = 0>
class embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >

Generic InstanceList template container.

This class is not intended to be used directly. Instead use the defined aliases:

DynamicInstanceList
StaticInstanceList

This list designed to work with STL containers and ETL containers which supply the push_back(), remove(), and remove_if() methods.

Using an InstanceList

For an example module which uses an InstanceList, see embvm::DriverBase.

The DriverBase InstanceList stores pointers to DriverBase instances, which is the base class for all framework drivers:

embutil::DynamicInstanceList<embvm::DriverBase, TKey>

When framework drivers are constructed, they are added to the DriverRegistry instance list. The registerDriver() interface forwards the call to the DriverRegistry add() function.

embvm::DriverBase::DriverBase(const char* name, uint32_t c) : name_(name), type_(c)
{
    VirtualPlatform::registerDriver(name_, this);
}
void DriverRegistry::add(const TKey name, embvm::DriverBase* driver)
{
 list_.add(name, driver);
}

The DeriverBase destructor removes instances from the list. The unregisterDriver() interface forwards the call to the DriverRegistry remove() function.

embvm::DriverBase::~DriverBase()
{
    VirtualPlatform::unregisterDriver(name_, this);
}
void DriverRegistry::remove(const TKey name, embvm::DriverBase* driver)
{
 list_.remove(name, driver);
}

Lookups can be performed by key:

auto find(const TKey name)
{
 return list_.find(name);
}
The return type of find() is a type_safe::optional_ref<TTrackedClass>. If the value is found,
The optional_ref will be valid and can be used. If the value is not found, the optional_ref
will be marked as invalid. Validity can be determined with `operator bool()`:
@code
auto tof = VirtualPlatform::template findDriver<embvm::tof::sensor>();
if(tof)
{
    tof.value().registerReadCallback([](uint16_t v) { printf("ToF Range: %u mm\n", v); });
}
else
{
    assert(0 && "ToF Driver Missing");
}

Template Parameters

TTrackedClass	The type of class which is tracked by this instance list.
TKey	The key type which is used to lookup stored values.
TContainer	The container type used to store the instance list.
TSize	The maximum of elements to track with the list. If TSize is 0, then dynamic memory allocation will be used. Otherwise, static memory allocation is used and the maximum number of elements that can be tracked is TSize.

Public Types
using	TStorageType = InstanceElem< TTrackedClass, TKey >

Public Member Functions
	InstanceList ()=default
	Default constructor. More...

	~InstanceList ()=default
	Default destructor. More...

size_t	size () const noexcept
	Get the current size of the list. More...

constexpr size_t	capacity () const noexcept
	Get the total storage capacity of the list. More...

TContainer &	rawStorage () noexcept
	Registered instance list accessor. More...

Add Instances
void	add (TKey key, TTrackedClass *instance) noexcept
	Register an instance of the TTrackedClass with a key. More...

void	add (TTrackedClass *instance) noexcept
	Register an instance of the TTrackedClass without a key. More...

Remove Instances
void	remove (TKey key, TTrackedClass *instance) noexcept
	Remove instance matching key and value. More...

void	remove (TKey key) noexcept
	Remove all instances matchey key. More...

void	remove (TTrackedClass *instance) noexcept
	Remove an instance value from the list. More...

Instance Lookup
optional_ref	operator[] (TKey key) noexcept
	Indexing operator supports the use of key. More...

optional_ref	find (TKey key) noexcept
	Find instance using a key. More...

Private Types
using	optional_ref = type_safe::optional_ref< TTrackedClass >
	Convenience alias for optional references, used internally to the class. More...

Private Attributes
TContainer	registered_
	The list of registered instances. More...

Member Typedef Documentation

◆ optional_ref

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

using embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::optional_ref = type_safe::optional_ref<TTrackedClass>

private

Convenience alias for optional references, used internally to the class.

◆ TStorageType

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

using embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::TStorageType = InstanceElem<TTrackedClass, TKey>

Constructor & Destructor Documentation

◆ InstanceList()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::InstanceList ( )

default

Default constructor.

◆ ~InstanceList()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::~InstanceList ( )

default

Default destructor.

Member Function Documentation

◆ add() [1/2]

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

void embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add	(	TKey	key,
		TTrackedClass *	instance
	)

inlinenoexcept

Register an instance of the TTrackedClass with a key.

add() should be called in the base-class constructor of the instance type which you are tracking. See embvm::DriverBase for an example.

This function is marked noexcept because we want the program to terminate if an exception results from this call.

Parameters

key	The key to register the instance under.
instance	The instance pointer to track.

References assert, b, embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::capacity(), embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_, and embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::size().

Referenced by embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add().

◆ add() [2/2]

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

void embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add ( TTrackedClass * instance )

inlinenoexcept

Register an instance of the TTrackedClass without a key.

add() should be called in the base-class constructor of the instance type which you are tracking. See embvm::DriverBase for an example.

This function is marked noexcept because we want the program to terminate if an exception results from this call.

Parameters

instance The instance pointer to track.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add().

◆ capacity()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

constexpr size_t embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::capacity ( ) const

inlinenoexcept

Get the total storage capacity of the list.

Returns: the maximum size the InstanceList container can support.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

Referenced by embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add().

◆ find()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

optional_ref embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::find ( TKey key )

inlinenoexcept

Find instance using a key.

Parameters

key	The key to use for looking up the corresponding TTrackedClass value.

Returns: an optional_ref to the TTrackedClass value corresponding to key. If no value is found that matches the key, the optional_ref will be empty.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

Referenced by embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::operator[]().

◆ operator[]()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

optional_ref embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::operator[] ( TKey key )

inlinenoexcept

Indexing operator supports the use of key.

Allow indexing into this object's key ("compatible-key", "instance-key")

Parameters

key	The key to use for looking up the corresponding TTrackedClass value.

Returns: an optional_ref to the TTrackedClass value corresponding to key. If no value is found that matches the key, the optional_ref will be empty.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::find().

◆ rawStorage()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

TContainer& embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::rawStorage ( )

inlinenoexcept

Registered instance list accessor.

If you need to perform lookups or other complex operations on the list, but can't work through the InstanceList interface, you can get the raw storage.

Returns: a reference to the list storage instance

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

◆ remove() [1/3]

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

void embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::remove	(	TKey	key,
		TTrackedClass *	instance
	)

inlinenoexcept

Remove instance matching key and value.

Both the key and the value must match for the instance to be removed.

This function is marked noexcept because we want the program to terminate if an exception results from this call.

Parameters

key	The key corresponding to the instance to remove.
instance	The instance value to remove.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_, and remove().

◆ remove() [2/3]

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

void embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::remove ( TKey key )

inlinenoexcept

Remove all instances matchey key.

This function is marked noexcept because we want the program to terminate if an exception results from this call.

Parameters

key	The corresponding key to remove instances for.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

◆ remove() [3/3]

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

void embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::remove ( TTrackedClass * instance )

inlinenoexcept

Remove an instance value from the list.

This function is marked noexcept because we want the program to terminate if an exception results from this call.

Parameters

instance The pointer to the instance to remove from the list.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

◆ size()

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

size_t embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::size ( ) const

inlinenoexcept

Get the current size of the list.

Returns: the current number of elements in the list.

References embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_.

Referenced by embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add().

Member Data Documentation

◆ registered_

template<class TTrackedClass , typename TKey , class TContainer , const size_t TSize = 0>

TContainer embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::registered_

private

The list of registered instances.

Referenced by embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::add(), embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::capacity(), embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::find(), embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::rawStorage(), embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::remove(), and embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >::size().

Typedef Documentation

◆ DynamicInstanceList

template<class TTrackedClass , typename TKey = const char*, class TContainer = std::list<InstanceElem<TTrackedClass, TKey>>>

using embutil::DynamicInstanceList = typedef InstanceList<TTrackedClass, TKey, TContainer>

Template class to track instances of class-type things (dynamic memory variant)

This class supports tracking instances which can come and go during runtime. The DynamicInstanceList uses dynamic memory allocation.

Example declarations:

DynamicInstanceList<embvm::DriverBase> // Dynamic list of driver instances, indexed by string

DynamicInstanceList<embvm::DriverBase, uint32_t> // Key is a uint32_t, not a string

Template Parameters

TTrackedClass	The type of class which is tracked by this instance list.
TKey	The key type which is used to lookup stored values.
TContainer	The container type used to store the instance list.

◆ StaticInstanceList

template<class TTrackedClass , const size_t TSize = 32, typename TKey = const char*, class TContainer = etl::list<InstanceElem<TTrackedClass, TKey>, TSize>>

using embutil::StaticInstanceList = typedef InstanceList<TTrackedClass, TKey, TContainer, TSize>

Template class to track instances of class-type things (static memory variant)

This class supports tracking instances which can come and go during runtime. The StaticInstanceList uses static memory allocation.

Example declarations:

StaticInstanceList<embvm::DriverBase> //Fixed list of 32 (default) driver instances, indexed by
string StaticInstanceList<embvm::DriverBase, 64> //Specify size as 64
StaticInstanceList<embvm::DriverBase, 32, uint32_t> //Key is a uint32_t, not a string

Template Parameters

TTrackedClass	The type of class which is tracked by this instance list.
TSize	The maximum of elements to track with the list.
TKey	The key type which is used to lookup stored values.
TContainer	The container type used to store the instance list.

Classes

Typedefs

Detailed Description

Class Documentation

◆ embutil::InstanceElem

template<class TTrackedClass, typename TKey> struct embutil::InstanceElem< TTrackedClass, TKey >

Public Member Functions

Public Attributes

Member Function Documentation

◆ operator==()

Member Data Documentation

◆ key

◆ value

◆ embutil::InstanceList

template<class TTrackedClass, typename TKey, class TContainer, const size_t TSize = 0> class embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >

Using an InstanceList

Public Types

Public Member Functions

Private Types

Private Attributes

Member Typedef Documentation

◆ optional_ref

◆ TStorageType

Constructor & Destructor Documentation

◆ InstanceList()

◆ ~InstanceList()

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ capacity()

◆ find()

◆ operator[]()

◆ rawStorage()

◆ remove() [1/3]

◆ remove() [2/3]

◆ remove() [3/3]

◆ size()

Member Data Documentation

◆ registered_

Typedef Documentation

◆ DynamicInstanceList

◆ StaticInstanceList

template<class TTrackedClass, typename TKey>
struct embutil::InstanceElem< TTrackedClass, TKey >

template<class TTrackedClass, typename TKey, class TContainer, const size_t TSize = 0>
class embutil::InstanceList< TTrackedClass, TKey, TContainer, TSize >