Interfaces and components for building a virtual OS. More...

Collaboration diagram for Framework OS Infrastructure:

Namespaces
	embvm::cv
	Condition Variable types and definitions.

	embvm::tls
	Thread Local Storage types.

	embvm::once

	embvm::eventflag
	Event flag types and definitions.

	embvm::mutex
	Mutex types and definitions.

	embvm::semaphore
	Semaphore types and definitions.

	embvm::thread
	Thread types and definitions.

	embvm::msgqueue
	Message queue types and definitions.

	embvm::this_thread
	Functions that operate on the currently active thread.

Classes
class	embvm::VirtualConditionVariable
	Defines the VirtualConditionVariable interface. More...

class	embvm::VirtualEventFlag
	Defines the VirtualEventFlag interface. More...

class	embvm::VirtualHeap< THeapImpl >

class	embvm::VirtualMessageQueue< TType >
	Defines the VirtualMessageQueue interface. More...

class	embvm::VirtualMutex
	Defines the VirtualMutex interface. More...

class	embvm::VirtualOSFactory< TFactory >
	Factory interface for creating RTOS-related objects. More...

class	embvm::VirtualSemaphore
	Defines the VirtualSemaphore interface. More...

class	embvm::VirtualThread
	Defines the VirtualThread interface. More...

Typedefs
using	embvm::os_timeout_t = std::chrono::duration< uint64_t, std::nano >
	Timeout type used for OS-related functions. More...

Variables
constexpr os_timeout_t	embvm::OS_WAIT_FOREVER = os_timeout_t{UINT64_C(-1)}
	Create a WAIT_FOREVER alias which can be used. More...

Detailed Description

Interfaces and components for building a virtual OS.

Class Documentation

◆ embvm::VirtualConditionVariable

class embvm::VirtualConditionVariable

Defines the VirtualConditionVariable interface.

VirtualConditionVariable defines the common condition variable interfaces for a VirtualRTOS. RTOS implementations should derive from this base class.

The factory is responsible for creating the cv, so the constructor is not defined in this interface class.

Inheritance diagram for embvm::VirtualConditionVariable:

Public Member Functions
	VirtualConditionVariable (const VirtualConditionVariable &)=delete
	Delete the copy constructor. More...

const VirtualConditionVariable &	operator= (const VirtualConditionVariable &)=delete
	Delete the copy assignment operator. More...

	VirtualConditionVariable (VirtualConditionVariable &&)=default
	Default move constructor. More...

VirtualConditionVariable &	operator= (VirtualConditionVariable &&)=default
	Default move operator. More...

virtual bool	wait (embvm::VirtualMutex *mutex) noexcept=0
	Blocks the current thread until the condition variable is woken up or after the specified timeout duration. More...

virtual bool	wait (embvm::VirtualMutex *mutex, const embvm::os_timeout_t &timeout) noexcept=0

bool	wait (embvm::VirtualMutex *mutex, const embvm::cv::func_t &predicate) noexcept

bool	wait (embvm::VirtualMutex *mutex, const embvm::cv::func_t &predicate, const embvm::os_timeout_t &timeout=embvm::OS_WAIT_FOREVER) noexcept

virtual void	signal () noexcept=0
	notifies one waiting thread More...

void	notify_one () noexcept
	Alias for signal so we can work with STL types. More...

virtual void	broadcast () noexcept=0
	Notify all waiting threads. More...

void	notify_all () noexcept
	Alias for broadcast so we can work with STL types. More...

virtual embvm::cv::handle_t	native_handle () const noexcept=0

Protected Member Functions
	VirtualConditionVariable ()=default

virtual	~VirtualConditionVariable () noexcept
	Derived classes should ensure their destructor deletes the OS CV. More...

Constructor & Destructor Documentation

◆ VirtualConditionVariable() [1/3]

embvm::VirtualConditionVariable::VirtualConditionVariable ( const VirtualConditionVariable & )

delete

Delete the copy constructor.

◆ VirtualConditionVariable() [2/3]

embvm::VirtualConditionVariable::VirtualConditionVariable ( VirtualConditionVariable && )

default

Default move constructor.

◆ VirtualConditionVariable() [3/3]

embvm::VirtualConditionVariable::VirtualConditionVariable ( )

protecteddefault

◆ ~VirtualConditionVariable()

VirtualConditionVariable::~VirtualConditionVariable ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS CV.

Member Function Documentation

◆ broadcast()

virtual void embvm::VirtualConditionVariable::broadcast ( )

pure virtualnoexcept

Notify all waiting threads.

Implemented in os::posix::ConditionVariable, and os::freertos::ConditionVariable.

Referenced by notify_all().

◆ native_handle()

virtual embvm::cv::handle_t embvm::VirtualConditionVariable::native_handle ( ) const

pure virtualnoexcept

Implemented in os::posix::ConditionVariable, and os::freertos::ConditionVariable.

◆ notify_all()

void embvm::VirtualConditionVariable::notify_all ( )

inlinenoexcept

Alias for broadcast so we can work with STL types.

References broadcast().

◆ notify_one()

void embvm::VirtualConditionVariable::notify_one ( )

inlinenoexcept

Alias for signal so we can work with STL types.

References signal().

◆ operator=() [1/2]

const VirtualConditionVariable& embvm::VirtualConditionVariable::operator= ( const VirtualConditionVariable & )

delete

Delete the copy assignment operator.

◆ operator=() [2/2]

VirtualConditionVariable& embvm::VirtualConditionVariable::operator= ( VirtualConditionVariable && )

default

Default move operator.

◆ signal()

virtual void embvm::VirtualConditionVariable::signal ( )

pure virtualnoexcept

notifies one waiting thread

Implemented in os::posix::ConditionVariable, and os::freertos::ConditionVariable.

Referenced by notify_one().

◆ wait() [1/4]

virtual bool embvm::VirtualConditionVariable::wait ( embvm::VirtualMutex * mutex )

pure virtualnoexcept

Blocks the current thread until the condition variable is woken up or after the specified timeout duration.

Implemented in os::freertos::ConditionVariable, and os::posix::ConditionVariable.

Referenced by wait().

◆ wait() [2/4]

virtual bool embvm::VirtualConditionVariable::wait	(	embvm::VirtualMutex *	mutex,
		const embvm::os_timeout_t &	timeout
	)

pure virtualnoexcept

Implemented in os::freertos::ConditionVariable, and os::posix::ConditionVariable.

◆ wait() [3/4]

bool embvm::VirtualConditionVariable::wait	(	embvm::VirtualMutex *	mutex,
		const embvm::cv::func_t &	predicate
	)

inlinenoexcept

References wait().

◆ wait() [4/4]

bool embvm::VirtualConditionVariable::wait	(	embvm::VirtualMutex *	mutex,
		const embvm::cv::func_t &	predicate,
		const embvm::os_timeout_t &	timeout = `embvm::OS_WAIT_FOREVER`
	)

inlinenoexcept

We break when the predicate is true or when we've timed out

References wait().

◆ embvm::VirtualEventFlag

class embvm::VirtualEventFlag

Defines the VirtualEventFlag interface.

VirtualEventFlag defines the common event flag interfaces for a VirtualRTOS. RTOS implementations should derive from this base class.

The factory is responsible for creating the event flag, so the constructor is not defined in this interface class.

Inheritance diagram for embvm::VirtualEventFlag:

Public Member Functions
virtual embvm::eventflag::flag_t	get (embvm::eventflag::flag_t bits_wait, embvm::eventflag::option opt=embvm::eventflag::option::OR, bool clearOnExit=true, const embvm::os_timeout_t &timeout=embvm::OS_WAIT_FOREVER) noexcept=0
	Get (or wait for) event flags. More...

virtual void	set (embvm::eventflag::flag_t bits) noexcept=0
	Set event flags. More...

virtual void	setFromISR (embvm::eventflag::flag_t bits) noexcept=0
	Set event flags from an ISR. More...

virtual void	clear () noexcept=0
	Clear all event flag bits. More...

virtual embvm::eventflag::handle_t	native_handle () const noexcept=0
	Get the native handle for the event flags group object. More...

	VirtualEventFlag (const VirtualEventFlag &)=delete
	Delete the copy constructor. More...

const VirtualEventFlag &	operator= (const VirtualEventFlag &)=delete
	Delete the copy assignment operator. More...

	VirtualEventFlag (VirtualEventFlag &&)=default
	Default move constructor. More...

VirtualEventFlag &	operator= (VirtualEventFlag &&)=default
	Default move assignment operator. More...

Protected Member Functions
	VirtualEventFlag ()=default

virtual	~VirtualEventFlag () noexcept
	Derived classes should ensure their destructor deletes the OS event flag. More...

Constructor & Destructor Documentation

◆ VirtualEventFlag() [1/3]

embvm::VirtualEventFlag::VirtualEventFlag ( const VirtualEventFlag & )

delete

Delete the copy constructor.

◆ VirtualEventFlag() [2/3]

embvm::VirtualEventFlag::VirtualEventFlag ( VirtualEventFlag && )

default

Default move constructor.

◆ VirtualEventFlag() [3/3]

embvm::VirtualEventFlag::VirtualEventFlag ( )

protecteddefault

◆ ~VirtualEventFlag()

VirtualEventFlag::~VirtualEventFlag ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS event flag.

Member Function Documentation

◆ clear()

virtual void embvm::VirtualEventFlag::clear ( )

pure virtualnoexcept

Clear all event flag bits.

Postcondition: Event flag group value is reset to '0'.

Implemented in os::posix::EventFlag, and os::freertos::EventFlag.

◆ get()

virtual embvm::eventflag::flag_t embvm::VirtualEventFlag::get	(	embvm::eventflag::flag_t	bits_wait,
		embvm::eventflag::option	opt = `embvm::eventflag::option::OR`,
		bool	clearOnExit = `true`,
		const embvm::os_timeout_t &	timeout = `embvm::OS_WAIT_FOREVER`
	)

pure virtualnoexcept

Get (or wait for) event flags.

Get the event flag bits. If the required event flags are not set, this function will block the calling thread until the flags are set or the timeout expires.

To see all bits currently set, set bits_wait to ~0 and timeout_t to the minimal value (timeout_t(1)).

Parameters

bits_wait	A bitmask of bits to wait for in the event flags group.
opt	The wait option, which is combined with bits_wait to control the behavior of get(). embvm::eventflag::option::OR will return once any of the bits specified in bits_wait are set in the event flag group. embvm::eventflag::option::AND will only return once ALL of the bits specified in bits_wait are set in the event flag group.
clearOnExit	If true, all event flags that were specified in bits_wait and set in the event flag group will be set to 0. If false, event flag bits will not be modified.
timeout	Specify a timeout for the get operation. If OS_WAIT_FOREVER is supplied, this call will block until the event flags are set. Otherwise, the function will timeout after the elapsed time if flags are not set.

Returns: 0 if timeout, or flags that were currently set according to bits_wait

Implemented in os::posix::EventFlag, and os::freertos::EventFlag.

Referenced by embutil::InterruptQueue< std::mutex >::wait_and_pop().

◆ native_handle()

virtual embvm::eventflag::handle_t embvm::VirtualEventFlag::native_handle ( ) const

pure virtualnoexcept

Get the native handle for the event flags group object.

Returns: the native handle for this event flags object. The handle will always return the handle_t and it must be cast to the native handle type by the user.

Implemented in os::posix::EventFlag, and os::freertos::EventFlag.

◆ operator=() [1/2]

const VirtualEventFlag& embvm::VirtualEventFlag::operator= ( const VirtualEventFlag & )

delete

Delete the copy assignment operator.

◆ operator=() [2/2]

VirtualEventFlag& embvm::VirtualEventFlag::operator= ( VirtualEventFlag && )

default

Default move assignment operator.

◆ set()

virtual void embvm::VirtualEventFlag::set ( embvm::eventflag::flag_t bits )

pure virtualnoexcept

Set event flags.

Set event flags from a threaded context. Threads waiting on event flags (via get()) will be notified.

Parameters

bits	A bitmask representing the bits to set in the event flag group.

Implemented in os::posix::EventFlag, and os::freertos::EventFlag.

Referenced by embutil::InterruptQueue< std::mutex >::~InterruptQueue().

◆ setFromISR()

virtual void embvm::VirtualEventFlag::setFromISR ( embvm::eventflag::flag_t bits )

pure virtualnoexcept

Set event flags from an ISR.

Set event flags from an interrupt context. This call must not use a lock. Threads waiting on event flags (via get()) will be notified.

Parameters

bits	A bitmask representing the bits to set in the event flag group.

Implemented in os::posix::EventFlag, and os::freertos::EventFlag.

Referenced by embutil::InterruptQueue< std::mutex >::dispatch().

◆ embvm::VirtualHeap

class embvm::VirtualHeap

template<typename THeapImpl>
class embvm::VirtualHeap< THeapImpl >

Static Public Member Functions
static void	addBlock (void *addr, size_t size) noexcept

static void	init () noexcept

static void *	alloc (size_t size) noexcept

static void	free (void *addr) noexcept

Member Function Documentation

◆ addBlock()

template<typename THeapImpl >

static void embvm::VirtualHeap< THeapImpl >::addBlock	(	void *	addr,
		size_t	size
	)

inlinestaticnoexcept

References assert.

Referenced by malloc_addblock().

◆ alloc()

template<typename THeapImpl >

static void* embvm::VirtualHeap< THeapImpl >::alloc ( size_t size )

inlinestaticnoexcept

Referenced by malloc().

◆ free()

template<typename THeapImpl >

static void embvm::VirtualHeap< THeapImpl >::free ( void * addr )

inlinestaticnoexcept

References assert, and free().

Referenced by free().

◆ init()

template<typename THeapImpl >

static void embvm::VirtualHeap< THeapImpl >::init ( )

inlinestaticnoexcept

Referenced by __attribute__().

◆ embvm::VirtualMessageQueue

class embvm::VirtualMessageQueue

template<typename TType>
class embvm::VirtualMessageQueue< TType >

Defines the VirtualMessageQueue interface.

VirtualMessageQueue defines the common message queue interfaces for a VirtualRTOS. RTOS implementations should derive from this base class. This class is templated, because message queues can hold any type of data structure.

The factory is responsible for creating the message queue, so the constructor is not defined in this interface class.

Template Parameters

TType The type of data to be stored in the message queue.

Inheritance diagram for embvm::VirtualMessageQueue< TType >:

Public Member Functions
	VirtualMessageQueue (const VirtualMessageQueue &)=delete
	Deleted copy constructor. More...

const VirtualMessageQueue &	operator= (const VirtualMessageQueue &)=delete
	Deleted copy assignment operator. More...

	VirtualMessageQueue (VirtualMessageQueue &&) noexcept=default
	Default move constructor. More...

VirtualMessageQueue &	operator= (VirtualMessageQueue &&) noexcept=default
	Default move assignment operator. More...

virtual bool	push (TType val, embvm::os_timeout_t timeout=embvm::OS_WAIT_FOREVER) noexcept=0
	Post a message to the queue. More...

virtual std::optional< TType >	pop (embvm::os_timeout_t timeout=embvm::OS_WAIT_FOREVER) noexcept=0
	Retrieve a message from the queue. More...

virtual size_t	size () const noexcept=0
	Get the current size of the message queue. More...

virtual void	reset () noexcept=0
	Reset the message queue to an empty state. More...

virtual bool	empty () const noexcept=0
	Check if the message queue is empty. More...

virtual bool	full () const noexcept=0
	Check if the message queue is full. More...

virtual embvm::msgqueue::handle_t	native_handle () const noexcept=0
	Get the native handle for the message queue object. More...

Protected Member Functions
	VirtualMessageQueue ()=default

virtual	~VirtualMessageQueue () noexcept=default
	Derived classes should ensure their destructor deletes the OS msg queue. More...

Constructor & Destructor Documentation

◆ VirtualMessageQueue() [1/3]

template<typename TType >

embvm::VirtualMessageQueue< TType >::VirtualMessageQueue ( const VirtualMessageQueue< TType > & )

delete

Deleted copy constructor.

◆ VirtualMessageQueue() [2/3]

template<typename TType >

embvm::VirtualMessageQueue< TType >::VirtualMessageQueue ( VirtualMessageQueue< TType > && )

defaultnoexcept

Default move constructor.

◆ VirtualMessageQueue() [3/3]

template<typename TType >

embvm::VirtualMessageQueue< TType >::VirtualMessageQueue ( )

protecteddefault

◆ ~VirtualMessageQueue()

template<typename TType >

virtual embvm::VirtualMessageQueue< TType >::~VirtualMessageQueue ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS msg queue.

Member Function Documentation

◆ empty()

template<typename TType >

virtual bool embvm::VirtualMessageQueue< TType >::empty ( ) const

pure virtualnoexcept

Check if the message queue is empty.

Returns: true if the queue is empty, false otherwise.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ full()

template<typename TType >

virtual bool embvm::VirtualMessageQueue< TType >::full ( ) const

pure virtualnoexcept

Check if the message queue is full.

Returns: true if the queue is full, false otherwise.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ native_handle()

template<typename TType >

virtual embvm::msgqueue::handle_t embvm::VirtualMessageQueue< TType >::native_handle ( ) const

pure virtualnoexcept

Get the native handle for the message queue object.

Returns: the native handle for this message queue object. The handle will always return the handle_t and it must be cast to the native handle type by the user.

Implemented in os::freertos::MessageQueue< TType >.

◆ operator=() [1/2]

template<typename TType >

const VirtualMessageQueue& embvm::VirtualMessageQueue< TType >::operator= ( const VirtualMessageQueue< TType > & )

delete

Deleted copy assignment operator.

◆ operator=() [2/2]

template<typename TType >

VirtualMessageQueue& embvm::VirtualMessageQueue< TType >::operator= ( VirtualMessageQueue< TType > && )

defaultnoexcept

Default move assignment operator.

◆ pop()

template<typename TType >

virtual std::optional<TType> embvm::VirtualMessageQueue< TType >::pop ( embvm::os_timeout_t timeout = embvm::OS_WAIT_FOREVER )

pure virtualnoexcept

Retrieve a message from the queue.

Retrieve a message from the queue. This function blocks the calling thread until a message is received (if OS_WAIT_FOREVER is specified as a timeout), or until the timeout expires.

Parameters

timeout The time to wait for a new message. A value of OS_WAIT_FOREVER indicates that the thread should block until a new message is posted.

Returns: an optional value. Use has_value() member function to determine if the value is valid. A valid value is only returned on success.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ push()

template<typename TType >

virtual bool embvm::VirtualMessageQueue< TType >::push	(	TType	val,
		embvm::os_timeout_t	timeout = `embvm::OS_WAIT_FOREVER`
	)

pure virtualnoexcept

Post a message to the queue.

Post a message to the queue. This function blocks the calling thread until there is an available slot (if OS_WAIT_FOREVER is specified as a timeout), or until the timeout expires.

Posting a message to the queue will notify all threads waiting on a new message (via pop()).

Parameters

val	The data value to post to the queue.
timeout	The time to wait for a new message. A value of OS_WAIT_FOREVER indicates that the thread should block until a new message is posted.

Returns: true if the message was successfully posted, false otherwise.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ reset()

template<typename TType >

virtual void embvm::VirtualMessageQueue< TType >::reset ( )

pure virtualnoexcept

Reset the message queue to an empty state.

Postcondition: The message queue is emptied, with size 0.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ size()

template<typename TType >

virtual size_t embvm::VirtualMessageQueue< TType >::size ( ) const

pure virtualnoexcept

Get the current size of the message queue.

Size represents the number of elements stored, rather than the maximum size (aka capacity).

Returns: the current number of elements stored in the message queue.

Implemented in os::posix::MessageQueue< TType >, and os::freertos::MessageQueue< TType >.

◆ embvm::VirtualMutex

class embvm::VirtualMutex

Defines the VirtualMutex interface.

VirtualMutex defines the common mutex interfaces for a VirtualRTOS. RTOS implementations should derive from this base class.

The factory is responsible for creating the mutex, so the constructor is not defined in this interface class.

Inheritance diagram for embvm::VirtualMutex:

Public Member Functions
	VirtualMutex (const VirtualMutex &)=delete
	Deleted copy constructor. More...

const VirtualMutex &	operator= (const VirtualMutex &)=delete
	Deleted copy assignment operator. More...

	VirtualMutex (VirtualMutex &&)=default
	Default move constructor. More...

VirtualMutex &	operator= (VirtualMutex &&)=default
	Default move assignment operator. More...

virtual void	lock () noexcept=0
	Lock the mutex. More...

virtual void	unlock () noexcept=0
	Unlock the mutex. More...

virtual bool	trylock () noexcept=0
	Try to lock the mutex. More...

virtual embvm::mutex::handle_t	native_handle () const noexcept=0

Protected Member Functions
	VirtualMutex ()=default

virtual	~VirtualMutex () noexcept
	Derived classes should ensure their destructor deletes the OS mutex. More...

Constructor & Destructor Documentation

◆ VirtualMutex() [1/3]

embvm::VirtualMutex::VirtualMutex ( const VirtualMutex & )

delete

Deleted copy constructor.

◆ VirtualMutex() [2/3]

embvm::VirtualMutex::VirtualMutex ( VirtualMutex && )

default

Default move constructor.

◆ VirtualMutex() [3/3]

embvm::VirtualMutex::VirtualMutex ( )

protecteddefault

◆ ~VirtualMutex()

VirtualMutex::~VirtualMutex ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS mutex.

Member Function Documentation

◆ lock()

virtual void embvm::VirtualMutex::lock ( )

pure virtualnoexcept

Lock the mutex.

Attempts to lock the mutex. If successful, the function returns with the calling thread owning the lock. If the lock is already owned, the calling thread will block until the lock is available.

Postcondition: The mutex is locked and owned by the calling thread.

Implemented in os::posix::Mutex, and os::freertos::Mutex.

◆ native_handle()

virtual embvm::mutex::handle_t embvm::VirtualMutex::native_handle ( ) const

pure virtualnoexcept

Implemented in os::posix::Mutex, and os::freertos::Mutex.

◆ operator=() [1/2]

const VirtualMutex& embvm::VirtualMutex::operator= ( const VirtualMutex & )

delete

Deleted copy assignment operator.

◆ operator=() [2/2]

VirtualMutex& embvm::VirtualMutex::operator= ( VirtualMutex && )

default

Default move assignment operator.

◆ trylock()

virtual bool embvm::VirtualMutex::trylock ( )

pure virtualnoexcept

Try to lock the mutex.

Try to lock the mutex, but don't block the thread if the mutex is already owned.

Postcondition: If the mutex is unowned, the mutex will be locked and owned by the calling thread.

Returns: true if the mutex is successfully locked, false if another thread owns the mutex.

Implemented in os::posix::Mutex, and os::freertos::Mutex.

◆ unlock()

virtual void embvm::VirtualMutex::unlock ( )

pure virtualnoexcept

Unlock the mutex.

Precondition: The mutex is locked and owned by the calling thread.

Postcondition: The mutex is unlocked.

Implemented in os::posix::Mutex, and os::freertos::Mutex.

◆ embvm::VirtualOSFactory

class embvm::VirtualOSFactory

template<typename TFactory>
class embvm::VirtualOSFactory< TFactory >

Factory interface for creating RTOS-related objects.

This calls provides the virtual interface for creating RTOS objects.

We use the curiously recurring template pattern (CRTP) for this factory. To create a new factory for your OS, derive in the following way:

class newOS : public VirtualOSFactory<newOS>

The derived class must implement the _impl() versions of the functions defined here.

Template Parameters

TFactory Derived factory class which implements the functions as required by the target RTOS.

Public Member Functions
	VirtualOSFactory ()=default

	~VirtualOSFactory ()=default

Static Public Member Functions
static embvm::VirtualConditionVariable *	createConditionVariable () noexcept
	Create a virtual condition variable. More...

static embvm::VirtualThread *	createThread (std::string_view name, embvm::thread::func_t f, embvm::thread::input_t input=nullptr, embvm::thread::priority p=embvm::thread::priority::normal, size_t stack_size=DEFAULT_STACK_SIZE, void *stack_ptr=nullptr) noexcept
	Create a virtual thread. More...

static embvm::VirtualMutex *	createMutex (embvm::mutex::type type=embvm::mutex::type::defaultType, embvm::mutex::mode mode=embvm::mutex::mode::defaultMode) noexcept
	Create a virtual Mutex. More...

static embvm::VirtualSemaphore *	createBinarySemaphore () noexcept
	Create a virtual binary semaphore. More...

static embvm::VirtualSemaphore *	createSemaphore (embvm::semaphore::count_t ceiling, embvm::semaphore::count_t initial_count=-1) noexcept
	Create a virtual counting semaphore. More...

template<typename TType >
static embvm::VirtualMessageQueue< TType > *	createMessageQueue (size_t queue_length) noexcept
	Create a virtual message queue. More...

static embvm::VirtualEventFlag *	createEventFlag () noexcept
	Create a virtual event flag. More...

static void	destroy (embvm::VirtualThread *item) noexcept

static void	destroy (embvm::VirtualMutex *item) noexcept

static void	destroy (embvm::VirtualSemaphore *item) noexcept

static void	destroy (embvm::VirtualEventFlag *item) noexcept

static void	destroy (embvm::VirtualConditionVariable *item) noexcept

Public Attributes
friend	TFactory

Constructor & Destructor Documentation

◆ VirtualOSFactory()

template<typename TFactory >

embvm::VirtualOSFactory< TFactory >::VirtualOSFactory ( )

default

◆ ~VirtualOSFactory()

template<typename TFactory >

embvm::VirtualOSFactory< TFactory >::~VirtualOSFactory ( )

default

Member Function Documentation

◆ createBinarySemaphore()

template<typename TFactory >

static embvm::VirtualSemaphore* embvm::VirtualOSFactory< TFactory >::createBinarySemaphore ( )

inlinestaticnoexcept

Create a virtual binary semaphore.

Creates a virtual binary semaphore using the underlying RTOS. A generic embvm::VirtualSemaphore pointer is returned, masking the underlying implementation from higher layers.

A binary semaphore is limited to a count of 1.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Returns: a embvm::VirtualSemaphore pointer

References embvm::semaphore::binary.

◆ createConditionVariable()

template<typename TFactory >

static embvm::VirtualConditionVariable* embvm::VirtualOSFactory< TFactory >::createConditionVariable ( )

inlinestaticnoexcept

Create a virtual condition variable.

Creates a condition variable using the underlying platform RTOS. A generic embvm::VirtualConditionVariable pointer is returned, masking the underlying implementation from higher layers.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Returns: a embvm::VirtualConditionVariable pointer

◆ createEventFlag()

template<typename TFactory >

static embvm::VirtualEventFlag* embvm::VirtualOSFactory< TFactory >::createEventFlag ( )

inlinestaticnoexcept

Create a virtual event flag.

Creates a virtual event flag using the underlying RTOS. A generic embvm::VirtualEventFlag pointer is returned, masking the underlying implementation from higher layers.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Returns: a embvm::VirtualEventFlag pointer.

Referenced by embutil::InterruptQueue< std::mutex >::InterruptQueue().

◆ createMessageQueue()

template<typename TFactory >

template<typename TType >

static embvm::VirtualMessageQueue<TType>* embvm::VirtualOSFactory< TFactory >::createMessageQueue ( size_t queue_length )

inlinestaticnoexcept

Create a virtual message queue.

Creates a virtual message queue using the underlying RTOS. The type of data stored in the message queue is determined using a template parameter. A generic embvm::VirtualMessageQueue pointer is returned, masking the underlying implementation from higher layers.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Template Parameters

TType The type of the underlying data to be stored.

Parameters

queue_length The maximum number of elements to store in the queue.

Returns: a embvm::VirtualMessageQueue<TType> pointer.

◆ createMutex()

template<typename TFactory >

static embvm::VirtualMutex* embvm::VirtualOSFactory< TFactory >::createMutex	(	embvm::mutex::type	type = `embvm::mutex::type::defaultType`,
		embvm::mutex::mode	mode = `embvm::mutex::mode::defaultMode`
	)

inlinestaticnoexcept

Create a virtual Mutex.

Creates a virtual mutex using the underlying RTOS. A generic embvm::VirtualMutex pointer is returned, masking the underlying implementation from higher layers.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Parameters

type	The type of mutex to create.
mode	The mutex's operational mode.

Returns: a embvm::VirtualMutex pointer.

References type.

◆ createSemaphore()

template<typename TFactory >

static embvm::VirtualSemaphore* embvm::VirtualOSFactory< TFactory >::createSemaphore	(	embvm::semaphore::count_t	ceiling,
		embvm::semaphore::count_t	initial_count = `-1`
	)

inlinestaticnoexcept

Create a virtual counting semaphore.

Creates a virtual counting semaphore using the underlying RTOS. A generic embvm::VirtualSemaphore pointer is returned, masking the underlying implementation from higher layers.

The counting semaphore supports counts > 1.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Parameters

ceiling	The maximum count the semaphore supports.
initial_count	Sets the initial count of the semaphore variable. Initial-count enables support for starting the semaphore with resources in use. Negative value indicates default setting - match ceiling

Returns: a embvm::VirtualSemaphore pointer.

References embvm::semaphore::counting.

◆ createThread()

template<typename TFactory >

static embvm::VirtualThread* embvm::VirtualOSFactory< TFactory >::createThread	(	std::string_view	name,
		embvm::thread::func_t	f,
		embvm::thread::input_t	input = `nullptr`,
		embvm::thread::priority	p = `embvm::thread::priority::normal`,
		size_t	stack_size = `DEFAULT_STACK_SIZE`,
		void *	stack_ptr = `nullptr`
	)

inlinestaticnoexcept

Create a virtual thread.

Creates a thread using the underlying platform RTOS. A generic embvm::VirtualThread pointer is returned, masking the underlying implementation from higher layers.

The caller owns the returnd pointer. It must be returned with the factory destroy() function.

Precondition: f is not nullptr

Postcondition: A thread object is created and the thread is started.

Parameters

name	The name of the thread.
f	The thread function which will be invoked. f must not be a nullptr.
input	Optional input value; nullptr can be specified for unused input.
p	Priority for the thread.
stack_size	the size of the thread's stack.
stack_ptr	Pointer to the thread's stack. nullptr input means dynamic memory will be used to allocate the stack.

Returns: a embvm::VirtualThread pointer

References assert, and p.

Referenced by nRF52DK_FrameworkDemoPlatform::initOS_(), and nRF52DK_FrameworkDemoPlatform::startBlink().

◆ destroy() [1/5]

template<typename TFactory >

static void embvm::VirtualOSFactory< TFactory >::destroy ( embvm::VirtualThread * item )

inlinestaticnoexcept

Referenced by embutil::InterruptQueue< std::mutex >::~InterruptQueue().

◆ destroy() [2/5]

template<typename TFactory >

static void embvm::VirtualOSFactory< TFactory >::destroy ( embvm::VirtualMutex * item )

inlinestaticnoexcept

◆ destroy() [3/5]

template<typename TFactory >

static void embvm::VirtualOSFactory< TFactory >::destroy ( embvm::VirtualSemaphore * item )

inlinestaticnoexcept

◆ destroy() [4/5]

template<typename TFactory >

static void embvm::VirtualOSFactory< TFactory >::destroy ( embvm::VirtualEventFlag * item )

inlinestaticnoexcept

◆ destroy() [5/5]

template<typename TFactory >

static void embvm::VirtualOSFactory< TFactory >::destroy ( embvm::VirtualConditionVariable * item )

inlinestaticnoexcept

Member Data Documentation

◆ TFactory

template<typename TFactory >

friend embvm::VirtualOSFactory< TFactory >::TFactory

◆ embvm::VirtualSemaphore

class embvm::VirtualSemaphore

Defines the VirtualSemaphore interface.

VirtualSemaphore defines the common semaphore interfaces for a VirtualRTOS. RTOS implementations should derive from this base class.

The factory is responsible for creating the semaphore, so the constructor is not defined in this interface class.

Inheritance diagram for embvm::VirtualSemaphore:

Public Member Functions
	VirtualSemaphore (const VirtualSemaphore &)=delete
	Delete the copy constructor. More...

const VirtualSemaphore &	operator= (const VirtualSemaphore &)=delete
	Delete the copy assignment operator. More...

	VirtualSemaphore (VirtualSemaphore &&)=default
	Default move constructor. More...

VirtualSemaphore &	operator= (VirtualSemaphore &&)=default
	Default move operator. More...

virtual void	give () noexcept=0
	Increment count Return a resource to the semaphore, incrementing the count. More...

virtual void	giveFromISR () noexcept=0
	Increment count from an ISR Return a resource to the semaphore, incrementing the count. More...

virtual bool	take (const embvm::os_timeout_t &timeout=embvm::OS_WAIT_FOREVER) noexcept=0
	Decrement count Take a resource from the semaphore, decrementing the count. More...

virtual embvm::semaphore::count_t	count () const noexcept=0
	Check the count of the semaphore. More...

virtual embvm::semaphore::handle_t	native_handle () const noexcept=0

Protected Member Functions
	VirtualSemaphore ()=default

virtual	~VirtualSemaphore () noexcept
	Derived classes should ensure their destructor deletes the OS semaphor. More...

Constructor & Destructor Documentation

◆ VirtualSemaphore() [1/3]

embvm::VirtualSemaphore::VirtualSemaphore ( const VirtualSemaphore & )

delete

Delete the copy constructor.

◆ VirtualSemaphore() [2/3]

embvm::VirtualSemaphore::VirtualSemaphore ( VirtualSemaphore && )

default

Default move constructor.

◆ VirtualSemaphore() [3/3]

embvm::VirtualSemaphore::VirtualSemaphore ( )

protecteddefault

◆ ~VirtualSemaphore()

VirtualSemaphore::~VirtualSemaphore ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS semaphor.

Member Function Documentation

◆ count()

virtual embvm::semaphore::count_t embvm::VirtualSemaphore::count ( ) const

pure virtualnoexcept

Check the count of the semaphore.

Returns: The current semaphore count.

Implemented in os::freertos::Semaphore.

◆ give()

virtual void embvm::VirtualSemaphore::give ( )

pure virtualnoexcept

Increment count Return a resource to the semaphore, incrementing the count.

Implemented in os::posix::Semaphore, and os::freertos::Semaphore.

◆ giveFromISR()

virtual void embvm::VirtualSemaphore::giveFromISR ( )

pure virtualnoexcept

Increment count from an ISR Return a resource to the semaphore, incrementing the count.

This function variant is safe to call from an interrupt routine. No locking can be used inside this variant.

Implemented in os::posix::Semaphore, and os::freertos::Semaphore.

◆ native_handle()

virtual embvm::semaphore::handle_t embvm::VirtualSemaphore::native_handle ( ) const

pure virtualnoexcept

Implemented in os::posix::Semaphore, and os::freertos::Semaphore.

◆ operator=() [1/2]

const VirtualSemaphore& embvm::VirtualSemaphore::operator= ( const VirtualSemaphore & )

delete

Delete the copy assignment operator.

◆ operator=() [2/2]

VirtualSemaphore& embvm::VirtualSemaphore::operator= ( VirtualSemaphore && )

default

Default move operator.

◆ take()

virtual bool embvm::VirtualSemaphore::take ( const embvm::os_timeout_t & timeout = embvm::OS_WAIT_FOREVER )

pure virtualnoexcept

Decrement count Take a resource from the semaphore, decrementing the count.

Parameters

timeout The time to wait for a semaphore resource. A value of WAIT_FOREVER indicates that the thread should block until the semaphore can be acquired.

Returns: true if take was successful, false if a timeout occurred.

Implemented in os::freertos::Semaphore.

◆ embvm::VirtualThread

class embvm::VirtualThread

Defines the VirtualThread interface.

VirtualThread defines the common thread interfaces for a VirtualRTOS. RTOS implementations should derive from this base class.

The factory is responsible for creating the thread, so the constructor is not defined in this interface class.

Inheritance diagram for embvm::VirtualThread:

Public Member Functions
	VirtualThread (const VirtualThread &)=delete
	Deleted copy constructor. More...

const VirtualThread &	operator= (const VirtualThread &)=delete
	Deleted copy assignment operator. More...

	VirtualThread (VirtualThread &&)=delete
	Default move constructor. More...

VirtualThread &	operator= (VirtualThread &&)=delete
	Default move assignment operator. More...

virtual embvm::thread::state	state () const noexcept=0
	Get the thread state. More...

virtual void	start () noexcept=0
	Start the thread, if it is not auto-started. More...

virtual void	terminate () noexcept=0
	Terminate a running thread. More...

virtual std::string_view	name () const noexcept=0
	View the thread's name. More...

virtual void	join () noexcept=0
	Join a running thread. More...

virtual embvm::thread::handle_t	native_handle () const noexcept=0
	Get the native handle for the thread. More...

Protected Member Functions
	VirtualThread ()=default

virtual	~VirtualThread () noexcept
	Derived classes should ensure their destructor deletes the OS task. More...

Constructor & Destructor Documentation

◆ VirtualThread() [1/3]

embvm::VirtualThread::VirtualThread ( const VirtualThread & )

delete

Deleted copy constructor.

◆ VirtualThread() [2/3]

embvm::VirtualThread::VirtualThread ( VirtualThread && )

delete

Default move constructor.

◆ VirtualThread() [3/3]

embvm::VirtualThread::VirtualThread ( )

protecteddefault

◆ ~VirtualThread()

VirtualThread::~VirtualThread ( )

protectedvirtualdefaultnoexcept

Derived classes should ensure their destructor deletes the OS task.

Member Function Documentation

◆ join()

virtual void embvm::VirtualThread::join ( )

pure virtualnoexcept

Join a running thread.

Joins a running thread, blocking the calling thread until the joined thread completes.

Precondition: The thread has not exited.

Postcondition: The thread has exited.

Implemented in os::posix::Thread, and os::freertos::Thread.

◆ name()

virtual std::string_view embvm::VirtualThread::name ( ) const

pure virtualnoexcept

View the thread's name.

Storage for the thread name is implementation defined. For example, the name may be stored in the RTOS memory, or it may require internal object storage.

Returns: The thread object's name.

Implemented in os::posix::Thread, and os::freertos::Thread.

◆ native_handle()

virtual embvm::thread::handle_t embvm::VirtualThread::native_handle ( ) const

pure virtualnoexcept

Get the native handle for the thread.

If custom extensions or behaviors are needed, the thread handle can be retrieved and manipulated directly.

Returns: the native thread object handle as a void*. The user must cast appropriately.

Implemented in os::posix::Thread, and os::freertos::Thread.

◆ operator=() [1/2]

const VirtualThread& embvm::VirtualThread::operator= ( const VirtualThread & )

delete

Deleted copy assignment operator.

◆ operator=() [2/2]

VirtualThread& embvm::VirtualThread::operator= ( VirtualThread && )

delete

Default move assignment operator.

◆ start()

virtual void embvm::VirtualThread::start ( )

pure virtualnoexcept

Start the thread, if it is not auto-started.

Implemented in os::posix::Thread, and os::freertos::Thread.

◆ state()

virtual embvm::thread::state embvm::VirtualThread::state ( ) const

pure virtualnoexcept

Get the thread state.

Returns: The state of the thread.

Implemented in os::posix::Thread, and os::freertos::Thread.

◆ terminate()

virtual void embvm::VirtualThread::terminate ( )

pure virtualnoexcept

Terminate a running thread.

Precondition: The thread is running.

Postcondition: The thread is aborted.

Implemented in os::posix::Thread, and os::freertos::Thread.

Typedef Documentation

◆ os_timeout_t

using embvm::os_timeout_t = typedef std::chrono::duration<uint64_t, std::nano>

Timeout type used for OS-related functions.

Variable Documentation

◆ OS_WAIT_FOREVER

constexpr os_timeout_t embvm::OS_WAIT_FOREVER = os_timeout_t{UINT64_C(-1)}

Create a WAIT_FOREVER alias which can be used.

Referenced by convert_timeout(), os::freertos::frameworkTimeoutToTicks(), and os::posix::ConditionVariable::wait().

Namespaces

Classes

Typedefs

Variables

Detailed Description

Class Documentation

◆ embvm::VirtualConditionVariable

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ VirtualConditionVariable() [1/3]

◆ VirtualConditionVariable() [2/3]

◆ VirtualConditionVariable() [3/3]

◆ ~VirtualConditionVariable()

Member Function Documentation

◆ broadcast()

◆ native_handle()

◆ notify_all()

◆ notify_one()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ signal()

◆ wait() [1/4]

◆ wait() [2/4]

◆ wait() [3/4]

◆ wait() [4/4]

◆ embvm::VirtualEventFlag

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ VirtualEventFlag() [1/3]

◆ VirtualEventFlag() [2/3]

◆ VirtualEventFlag() [3/3]

◆ ~VirtualEventFlag()

Member Function Documentation

◆ clear()

◆ get()

◆ native_handle()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set()

◆ setFromISR()

◆ embvm::VirtualHeap

template<typename THeapImpl> class embvm::VirtualHeap< THeapImpl >

Static Public Member Functions

Member Function Documentation

◆ addBlock()

◆ alloc()

◆ free()

◆ init()

◆ embvm::VirtualMessageQueue

template<typename TType> class embvm::VirtualMessageQueue< TType >

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ VirtualMessageQueue() [1/3]

◆ VirtualMessageQueue() [2/3]

◆ VirtualMessageQueue() [3/3]

◆ ~VirtualMessageQueue()

Member Function Documentation

◆ empty()

◆ full()

◆ native_handle()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pop()

◆ push()

◆ reset()

◆ size()

◆ embvm::VirtualMutex

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ VirtualMutex() [1/3]

◆ VirtualMutex() [2/3]

◆ VirtualMutex() [3/3]

◆ ~VirtualMutex()

Member Function Documentation

◆ lock()

◆ native_handle()

template<typename THeapImpl>
class embvm::VirtualHeap< THeapImpl >

template<typename TType>
class embvm::VirtualMessageQueue< TType >

template<typename TFactory>
class embvm::VirtualOSFactory< TFactory >