fiber::TaskBase Class Reference

A TaskBase (short for coroutine task) is the root of a linked list of nested coroutines. More...

#include <Coroutine.hpp>

Inheritance diagram for fiber::TaskBase:

Classes
struct	larger_ready_time_s
struct	less_priority_s

Public Member Functions
constexpr	TaskBase ()=default
constexpr	TaskBase (const TaskBase &)=delete
constexpr TaskBase &	operator= (const TaskBase &)=delete
constexpr	TaskBase (TaskBase &&other) noexcept
TaskBase &	operator= (TaskBase &&other) noexcept
template<class F, class... Args> requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>
constexpr	TaskBase (std::string_view task_name, fiber::StackAllocatorExtern *frame_allocator, F &&function, Args &&... args)
	constructor to create a priority-based task with the lowest priority
template<class F, class... Args> requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>
constexpr	TaskBase (std::string_view task_name, uint16_t priority, fiber::StackAllocatorExtern *frame_allocator, F &&function, Args &&... args)
	constructor to create a priority-based task that starts immediatelly
template<class F, class... Args> requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>
constexpr	TaskBase (std::string_view task_name, TimePoint ready, fiber::StackAllocatorExtern *frame_allocator, F &&function, Args &&... args)
	constructor to create a priority-based task that starts at a certain time point in the future
template<class F, class... Args> requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>
constexpr	TaskBase (std::string_view task_name, TimePoint ready, TimePoint deadline, fiber::StackAllocatorExtern *frame_allocator, F &&function, Args &&... args)
	constructor to create a real-time deadline-based task
template<class F, class... Args> requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>
constexpr	TaskBase (std::string_view task_name, TimePoint ready, Duration deadline, fiber::StackAllocatorExtern *frame_allocator, F &&function, Args &&... args)
	constructor to create a real-time deadline-based task
virtual	~TaskBase ()
virtual bool	missed_deadline (fiber::Duration d)
	Overrideable: Gets called if the deadline has been missed and decides wether the task should still execute or not.
virtual Schedule	next_schedule (Schedule previous_schedule, ExecutionTime previous_execution)
	Overrideable: Gets called after a co_await NextCycle; to calculate the schedule of the next cycle.
constexpr unsigned int	id () const
	returns the assigned id of the task.
constexpr bool	is_deadline_based () const
constexpr bool	is_priority_based () const
constexpr std::string_view	name () const
	returns the name of the task
constexpr std::size_t	max_frame_size () const
	returns the maximal allocatable size of the frame (stack allocator)
constexpr std::size_t	allocated_frame_size () const
	returns the allocated size of the frame (stack allocator)
constexpr std::size_t	max_allocated_frame_size () const
	returns the maximal allocated size in the frame since construction (stack allocator)
constexpr void	signal (const CoSignal &signal)
	sets a coroutine control signal.
constexpr const CoSignal	get_signal ()
	reads and clears the signal
constexpr void	destroy ()
	destroys all contained coroutines
constexpr void	register_leaf (CoroutineNode *leaf) noexcept
	Registers the leaf nested coroutine that serves as the resume point after suspensions.
template<class T>
constexpr void	register_leaf (const T *obj, bool(*func)(const T *obj)) noexcept
	Registers a leaf awaitable that will be waited on before resuming its parents coroutine.
void	resume ()
	resumes the task/coroutine
bool	is_resumable () const
	returns true if the awaitable that this task is waiting on is ready and .resume() can be called again
constexpr bool	is_awaiting () const
	returns true if the awaitable that this task is waiting on is still waiting for completion - aka. this task is not resumable
constexpr bool	is_done () const
	returns true if the main/root coroutine is done - thus the task is done
constexpr bool	await_ready () const noexcept
	same as is_done() but for interoperability with co_await
constexpr Exit	await_resume ()
	interoperability with co_await
constexpr Exit	exit_status ()
void	handle_exception (std::exception_ptr except_ptr)
	exception handler - will be called if an un-catched exception in a coroutine arises
TimePoint	ready_time () const
TimePoint	deadline () const
uint32_t	priority () const
bool	immediatelly_ready () const

Public Attributes
std::string_view	_task_name = ""
fiber::StackAllocatorExtern *	_frame_allocator
Coroutine< fiber::Exit >	_main_coroutine
CoroutineNode *	_leaf_coroutine = nullptr
bool(*	_leaf_awaitable_ready_func )(const void *_leaf_awaitable_obj) = nullptr
const void *	_leaf_awaitable_obj = nullptr
CoSignal	_signal
uint32_t	_priority = 0
Schedule	_schedule
TimePoint	_execution_start
uint16_t	_id = 0
bool	_instant_resume = false
bool	_immediatelly_ready = false

Static Public Attributes
static constexpr uint32_t	_deadline_priority = std::numeric_limits<uint32_t>::max()

Detailed Description

A TaskBase (short for coroutine task) is the root of a linked list of nested coroutines.

A TaskBase contains one or more (nested) coroutines in an acyclic graph. It will always resume the last/leaf coroutine and is done onece all coroutines have co_retuned.

A TaskBase is itsef an AwaitableNode and thus might be co_awaited by another task. This might be useful, for example if one task issues 3 other tasks to the scheduler, and the co_awaits all of them to continue its own execution only once all are finished.

The leaf coroutine can communicate to the TaskBase via the interface provided by the AwaitableNode that is co_awaited. Through co_await the leaf coroutine can send a signal to the TaskBase (and thus the scheduler) to tell that it is awaiting on some external task, hardware, I/O, etc.

You might customise the behaviour of the task by overloading the error handler, that will be invoked on uncaught exceptions.

virtual void handle_exception(std::exception_ptr except_ptr);

See also

fiber::AwaitableNode

fiber::LinearScheduler

Template Parameters

N	The number of bytes used for the tasks frame allocator

Constructor & Destructor Documentation

TaskBase() [1/8]

fiber::TaskBase::TaskBase ( )

constexprdefault

TaskBase() [2/8]

fiber::TaskBase::TaskBase ( const TaskBase & )

constexprdelete

TaskBase() [3/8]

fiber::TaskBase::TaskBase ( TaskBase && other )

inlineconstexprnoexcept

TaskBase() [4/8]

template<class F, class... Args>
requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>

fiber::TaskBase::TaskBase ( std::string_view task_name, fiber::StackAllocatorExtern * frame_allocator, F && function, Args &&... args )

inlineconstexpr

constructor to create a priority-based task with the lowest priority

Defaults to priority 1 (2nd lowest priority level, lowest priority is 0)

TaskBase() [5/8]

template<class F, class... Args>
requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>

fiber::TaskBase::TaskBase ( std::string_view task_name, uint16_t priority, fiber::StackAllocatorExtern * frame_allocator, F && function, Args &&... args )

inlineconstexpr

constructor to create a priority-based task that starts immediatelly

TaskBase() [6/8]

template<class F, class... Args>
requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>

fiber::TaskBase::TaskBase ( std::string_view task_name, TimePoint ready, fiber::StackAllocatorExtern * frame_allocator, F && function, Args &&... args )

inlineconstexpr

constructor to create a priority-based task that starts at a certain time point in the future

Defaults to priority 1 (2nd lowest priority level, lowest priority is 0)

TaskBase() [7/8]

template<class F, class... Args>
requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>

fiber::TaskBase::TaskBase ( std::string_view task_name, TimePoint ready, TimePoint deadline, fiber::StackAllocatorExtern * frame_allocator, F && function, Args &&... args )

inlineconstexpr

constructor to create a real-time deadline-based task

deadline based tasks automatically have int_max assigned to their priority (highest priority).

TaskBase() [8/8]

template<class F, class... Args>
requires std::invocable<F, Args...> && std::same_as<std::invoke_result_t<F, Args...>, Coroutine<fiber::Exit>>

fiber::TaskBase::TaskBase ( std::string_view task_name, TimePoint ready, Duration deadline, fiber::StackAllocatorExtern * frame_allocator, F && function, Args &&... args )

inlineconstexpr

constructor to create a real-time deadline-based task

deadline based tasks automatically have int_max assigned to their priority (highest priority).

~TaskBase()

virtual fiber::TaskBase::~TaskBase ( )

inlinevirtual

Member Function Documentation

allocated_frame_size()

std::size_t fiber::TaskBase::allocated_frame_size ( ) const

inlineconstexpr

returns the allocated size of the frame (stack allocator)

await_ready()

bool fiber::TaskBase::await_ready ( ) const

inlineconstexprnoexcept

same as is_done() but for interoperability with co_await

await_resume()

Exit fiber::TaskBase::await_resume ( )

constexpr

interoperability with co_await

deadline()

TimePoint fiber::TaskBase::deadline ( ) const

inline

destroy()

void fiber::TaskBase::destroy ( )

inlineconstexpr

destroys all contained coroutines

exit_status()

Exit fiber::TaskBase::exit_status ( )

constexpr

get_signal()

const CoSignal fiber::TaskBase::get_signal ( )

inlineconstexpr

reads and clears the signal

handle_exception()

void fiber::TaskBase::handle_exception

(

std::exception_ptr

except_ptr

)

exception handler - will be called if an un-catched exception in a coroutine arises

id()

unsigned int fiber::TaskBase::id ( ) const

inlineconstexpr

returns the assigned id of the task.

Has likely been assigned by the scheduler

immediatelly_ready()

bool fiber::TaskBase::immediatelly_ready ( ) const

inline

is_awaiting()

bool fiber::TaskBase::is_awaiting ( ) const

inlineconstexpr

returns true if the awaitable that this task is waiting on is still waiting for completion - aka. this task is not resumable

equivalent to !task->is_resumable()

is_deadline_based()

bool fiber::TaskBase::is_deadline_based ( ) const

inlineconstexpr

is_done()

bool fiber::TaskBase::is_done ( ) const

inlineconstexpr

returns true if the main/root coroutine is done - thus the task is done

is_priority_based()

bool fiber::TaskBase::is_priority_based ( ) const

inlineconstexpr

is_resumable()

bool fiber::TaskBase::is_resumable

(

)

const

returns true if the awaitable that this task is waiting on is ready and .resume() can be called again

also returns true if there is currently no awaitable that is being waited on.

max_allocated_frame_size()

std::size_t fiber::TaskBase::max_allocated_frame_size ( ) const

inlineconstexpr

returns the maximal allocated size in the frame since construction (stack allocator)

max_frame_size()

std::size_t fiber::TaskBase::max_frame_size ( ) const

inlineconstexpr

returns the maximal allocatable size of the frame (stack allocator)

missed_deadline()

virtual bool fiber::TaskBase::missed_deadline ( fiber::Duration d )

inlinevirtual

Overrideable: Gets called if the deadline has been missed and decides wether the task should still execute or not.

Parameters

d	The duration/time that passed since the deadline

The default version will always return true to continue the task

Returns

Returns if the task should still be executed (true) or not (false)

name()

std::string_view fiber::TaskBase::name ( ) const

inlineconstexpr

returns the name of the task

next_schedule()

virtual Schedule fiber::TaskBase::next_schedule ( Schedule previous_schedule, ExecutionTime previous_execution )

inlinevirtual

Overrideable: Gets called after a co_await NextCycle; to calculate the schedule of the next cycle.

Note that previous_execution.end is equivalent to the current time .aka now()

Parameters

previous_schedule	the previous schedule of this task
previous_execution	the previous execution time from the start of the cycle to the end of the cycle

operator=() [1/2]

TaskBase & fiber::TaskBase::operator= ( const TaskBase & )

constexprdelete

operator=() [2/2]

TaskBase & fiber::TaskBase::operator= ( TaskBase && other )

inlinenoexcept

priority()

uint32_t fiber::TaskBase::priority ( ) const

inline

ready_time()

TimePoint fiber::TaskBase::ready_time ( ) const

inline

register_leaf() [1/2]

template<class T>

void fiber::TaskBase::register_leaf ( const T * obj, bool(* func )(const T *obj) )

inlineconstexprnoexcept

Registers a leaf awaitable that will be waited on before resuming its parents coroutine.

Meant to be called by the Awaitable

Parameters

awaitable

The awaitable that will be waited on

register_leaf() [2/2]

void fiber::TaskBase::register_leaf ( CoroutineNode * leaf )

inlineconstexprnoexcept

Registers the leaf nested coroutine that serves as the resume point after suspensions.

Meant to be called by the Coroutine

Parameters

leaf	a coroutine handle to the leaf tasks

resume()

void fiber::TaskBase::resume

(

)

resumes the task/coroutine

This the only resume point for the whole coroutine chain. Every coroutine and nested coroutine suspends to here and will be executed/resumed from here by resuming the leaf/tail of the coroutine linked list.

Note: a task needs to be resumeable, that is is_resumeable() returns true before calling this method. Otherwise an assertion is thrown at ASSERTION_LEVEL_O1 or higher - if lower: Undefined behaviour UB ⚠.

Exceptions

An	AssertionFailuer if resumed while is_resumeable() is false, but only in ASSERTION_LEVEL_O1 or higher

signal()

void fiber::TaskBase::signal ( const CoSignal & signal )

inlineconstexpr

sets a coroutine control signal.

Used by the coroutine or awaitable to set a control signal. Can be used to influence the runtime behaviour of the task, or the way the scheduler continues scheduling it.

Member Data Documentation

_deadline_priority

uint32_t fiber::TaskBase::_deadline_priority = std::numeric_limits<uint32_t>::max()

staticconstexpr

_execution_start

TimePoint fiber::TaskBase::_execution_start

_frame_allocator

fiber::StackAllocatorExtern* fiber::TaskBase::_frame_allocator

_id

uint16_t fiber::TaskBase::_id = 0

_immediatelly_ready

bool fiber::TaskBase::_immediatelly_ready = false

_instant_resume

bool fiber::TaskBase::_instant_resume = false

_leaf_awaitable_obj

const void* fiber::TaskBase::_leaf_awaitable_obj = nullptr

_leaf_awaitable_ready_func

bool(* fiber::TaskBase::_leaf_awaitable_ready_func) (const void *_leaf_awaitable_obj) = nullptr

_leaf_coroutine

CoroutineNode* fiber::TaskBase::_leaf_coroutine = nullptr

_main_coroutine

Coroutine<fiber::Exit> fiber::TaskBase::_main_coroutine

_priority

uint32_t fiber::TaskBase::_priority = 0

_schedule

Schedule fiber::TaskBase::_schedule

_signal

CoSignal fiber::TaskBase::_signal

_task_name

std::string_view fiber::TaskBase::_task_name = ""

---

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

• fiber/OS/Coroutine.hpp
• fiber/OS/Coroutine.cpp