Framework Utilities

Embedded Framework utility classes and functions. More...

Collaboration diagram for Framework Utilities:

Modules
	Special Function Register
	Safer types for working with special-function registers.
	Bit Manipulation
	Functions and macros that operate in a bitwise manner.
	Dispatch Queues
	Group of worker threads that enables asynchronous processing.
	Endian Swap
	Functions that can be used to swap the endianness of a value.
	Function Queue
	Queues for storing function objects.
	Instance List
	Supports tracking instances which can come and go during runtime.
	C Linked List Interface
	A linked list library for C modules.
	Scope-bound Resource Management
	Utilties that enable SBRM techniques.
	Time Utilities
	Functions that work with C and C++ time types.
	Volatile load/store
	These functions promote safer loading and storing of volatile values.

Classes
class	embutil::InterruptLock< InterruptLockPolicy >
	BasicLockable class which disables/enables interrupts. More...

Functions
template<class TClass , class Method , Method m, class... Params>
static auto	embutil::bounce (void *priv, Params... params) noexcept -> decltype(((*reinterpret_cast< TClass * >(priv)).*m)(params...))
	Enable a C++ member function to work with a C-style callback interface. More...

Detailed Description

Embedded Framework utility classes and functions.

---

Class Documentation

embutil::InterruptLock

class embutil::InterruptLock

template<typename InterruptLockPolicy>
class embutil::InterruptLock< InterruptLockPolicy >

BasicLockable class which disables/enables interrupts.

This class defines a BasicLockable interface for enabling and disabling interrupts. The lock() function is used to disable interrupts, and unlock() to enable them.

Note

This lock is not re-entrant.

Public Member Functions
	InterruptLock ()=default
	Default constructor. More...
	~InterruptLock ()=default
	Default destructor. More...
	InterruptLock (const InterruptLock &)=delete
	Deleted copy constructor. More...
const InterruptLock &	operator= (const InterruptLock &)=delete
	Deleted copy assignment operator. More...
	InterruptLock (InterruptLock &&)=default
	Deleted move constructor. More...
InterruptLock &	operator= (InterruptLock &&)=default
	Deleted move assignment operator. More...
void	lock () noexcept
void	unlock () noexcept
	Enable interrupts to leave critical section. More...
Private Attributes
InterruptLockPolicy::TReturn	irq_status_
	Local storage for the disable function result, which is passed into the enable function to ensure we restore the prior value. More...

Constructor & Destructor Documentation

InterruptLock() [1/3]

template<typename InterruptLockPolicy >

embutil::InterruptLock< InterruptLockPolicy >::InterruptLock ( )

default

Default constructor.

~InterruptLock()

template<typename InterruptLockPolicy >

embutil::InterruptLock< InterruptLockPolicy >::~InterruptLock ( )

default

Default destructor.

InterruptLock() [2/3]

template<typename InterruptLockPolicy >

embutil::InterruptLock< InterruptLockPolicy >::InterruptLock ( const InterruptLock< InterruptLockPolicy > &  )

delete

Deleted copy constructor.

InterruptLock() [3/3]

template<typename InterruptLockPolicy >

embutil::InterruptLock< InterruptLockPolicy >::InterruptLock ( InterruptLock< InterruptLockPolicy > &&  )

default

Deleted move constructor.

Member Function Documentation

lock()

template<typename InterruptLockPolicy >

void embutil::InterruptLock< InterruptLockPolicy >::lock ( )

inlinenoexcept

References embutil::InterruptLock< InterruptLockPolicy >::irq_status_.

operator=() [1/2]

template<typename InterruptLockPolicy >

const InterruptLock& embutil::InterruptLock< InterruptLockPolicy >::operator= ( const InterruptLock< InterruptLockPolicy > &  )

delete

Deleted copy assignment operator.

operator=() [2/2]

template<typename InterruptLockPolicy >

InterruptLock& embutil::InterruptLock< InterruptLockPolicy >::operator= ( InterruptLock< InterruptLockPolicy > &&  )

default

Deleted move assignment operator.

unlock()

template<typename InterruptLockPolicy >

void embutil::InterruptLock< InterruptLockPolicy >::unlock ( )

inlinenoexcept

Enable interrupts to leave critical section.

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

References embutil::InterruptLock< InterruptLockPolicy >::irq_status_.

Member Data Documentation

irq_status_

template<typename InterruptLockPolicy >

InterruptLockPolicy::TReturn embutil::InterruptLock< InterruptLockPolicy >::irq_status_

private

Local storage for the disable function result, which is passed into the enable function to ensure we restore the prior value.

Referenced by embutil::InterruptLock< InterruptLockPolicy >::lock(), and embutil::InterruptLock< InterruptLockPolicy >::unlock().

Function Documentation

bounce()

template<class TClass , class Method , Method m, class... Params>

static auto embutil::bounce ( void *  priv, Params...  params  ) -> decltype(((*reinterpret_cast<TClass*>(priv)).*m)(params...))

staticnoexcept

Enable a C++ member function to work with a C-style callback interface.

This function is intended to be passed to a C-style callback system which takes a function pointer and private data pointer as input values. Using C-style callbacks is problematic with object member functions, as you need the object's pointer to get to the correct instance.

This bounce function requires use of the private data pointer in a C-style callback. The data pointer must be used for the object's instance pointer. Any other provided arguments are forwarded to the object's member function, and the return value is passed to the caller.

You can simplify this call with the BOUNCE() macro.

You may need to reinterpret_cast the bounce function to the expected type:

reinterpret_cast<void*(*)(void*)>(BOUNCE(c, function))

You will need to couple a bounce function with the this pointer as a function input to get to the correct instance.

Example usage with a C-style callback interface

posixThread is a C++ class, and posixThread::thread_func() is a member function which we want to pass to pthread_create(). The this pointer is captured and passed into the private input data argument, which is forwarded to the thread.

void* posixThread::thread_func()
{...}

[...]

// Our interfaces demand a void(*)(void*), so we adapt to posix's requirement
// and simply skip out on the return to the caller's perspective
r = pthread_create(&handle_, &attributes,
 reinterpret_cast<void* (*)(void*)>(
    embutil::bounce<posixThread, decltype(&posixThread::thread_func),
 &posixThread::thread_func>), *     reinterpret_cast<void*>(this));

The use case above is too verbose, so we recommend the BOUNCE() macro instead:

BOUNCE(posixThread, thread_func);

This function is marked noexcept because we want the program to terminate if an exception results from this call. We can't guarantee the bounce function won't throw.

Template Parameters

TClass	The type of class with the member function to be used as a callback.
Method	The type of the member function to use as a callback.
m	The function pointer corresponding to the class's member function.
Params	Variadic template list of function parameters to forward to the member function.

Parameters

priv	The private data pointer, which must always be passed the class's this pointer so bounce can resolve to the correct instance.
params	Variadic list of parameters to forward to the member function.

Returns

the value returned by the member function.