This class implements an execution of tasks pulled off an input queue. More...

#include <Executor.hxx>

Inheritance diagram for ExecutorBase:

Public Member Functions
	ExecutorBase ()
	Constructor.

	~ExecutorBase ()
	Destructor.

virtual void	add (Executable *action, unsigned priority=UINT_MAX)=0
	Send a message to this Executor's queue.

void	sync_run (std::function< void()> fn)
	Synchronously runs a closure on this executor.

void	select (Selectable *job)
	Adds a file descriptor to be watched to the select loop.

bool	is_selected (Selectable *job)

void	unselect (Selectable *job)
	Removes a job from the select loop.

bool	loop_once ()
	Performs one loop of the execution on the calling thread.

long long	loop_some () ICACHE_FLASH_ATTR
	Performs a few loops of the executor on the calling thread.

ActiveTimers *	active_timers ()

void	shutdown ()
	Terminates the executor thread.

virtual bool	empty ()=0

os_thread_t	thread_handle ()

OSThread &	thread ()

void	assert_current ()
	Die if we are not on the current executor.

virtual uint32_t	sequence ()=0

Executable *	current ()
	Helper function for debugging and tracing.

Public Member Functions inherited from LinkedObject< ExecutorBase >
ExecutorBase *	link_next ()

Static Public Member Functions
static ExecutorBase *	by_name (const char *name, bool wait)
	Lookup an executor by its name.

Static Public Member Functions inherited from LinkedObject< ExecutorBase >
static ExecutorBase *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Protected Member Functions
void *	entry () override
	Thread entry point.

void	run () override
	Entry point.

	DISALLOW_COPY_AND_ASSIGN (ExecutorBase)

	OSThread (const char name, int priority, size_t stack_size, void (start_routine)(void ), void *arg)
	Create a thread.

	OSThread ()
	Creates a thread via inheritance.

void	start (const char *name, int priority, size_t stack_size)
	Starts the thread.

virtual	~OSThread ()
	Default destructor.

bool	is_created ()

void	inherit ()
	Inherits the current thread.

os_thread_t	get_handle ()

void	lock_to_thread ()
	Sets the thread handle to the current calling thread's.

void	unlock_from_thread ()
	Resets the thread handle to none.

Protected Member Functions inherited from Executable
void	test_deletion ()

void	notify () override
	Crashes the program – everyone who is expecting notify calls must override this function.

virtual void	alloc_result (QMember *item)
	Return the result of an alloc_async() from a memory Pool.

Protected Member Functions inherited from QMember
	QMember ()
	Constructor.

	~QMember ()
	Destructor.

void	init ()
	Initiailize a QMember, in place of a public placement construction.

Protected Member Functions inherited from LinkedObject< ExecutorBase >
ExecutorBase *	link_this ()

	LinkedObject ()
	Constructor. Puts *this on the linked list.

	~LinkedObject ()
	Constructor. Removes *this from the linked list.

ExecutorBase *	link_next ()

Protected Attributes
OSSelectWakeup	selectHelper_
	Helper object for interruptible select calls.

volatile unsigned	sequence_: 25
	Sequence number.

Protected Attributes inherited from QMember
QMember *	next
	pointer to the next member in the queue

Protected Attributes inherited from LinkedObject< ExecutorBase >
ExecutorBase *	link_
	Linked list pointer.

Private Member Functions
virtual Executable *	next (unsigned *priority)=0
	Retrieve an item from the front of the queue.

void	wait_with_select (long long next_timer_nsec)
	Executes a select call, and schedules any necessary executables based on the return.

fd_set *	get_select_set (Selectable::SelectType type)
	Helper function.

Private Attributes
const char *	name_
	name of this Executor

Executable *volatile	current_
	Currently executing closure.

ActiveTimers	activeTimers_
	List of active timers.

fd_set	selectRead_
	fd to select for read.

fd_set	selectWrite_
	fd to select for write.

fd_set	selectExcept_
	fd to select for except.

int	selectNFds_
	maximum fd to select for + 1

TypedQueue< Selectable >	selectables_
	Head of the linked list for the select calls.

std::atomic_uint_least8_t	done_
	Set to 1 when the executor thread has exited and it is safe to delete *this.

std::atomic_uint_least8_t	started_
	1 if the executor is already running

unsigned	selectPrescaler_: 5
	How many executables we schedule blindly before calling a select() in order to find more data to read/write in the FDs being waited upon.

Friends
class	Service
	provide access to Executor::send method.

Additional Inherited Members
Static Protected Member Functions inherited from OSThread
static int	getpriority (OSThread *thread)
	Return the current thread priority.

static int	get_priority (OSThread *thread)
	Return the current thread priority.

static int	get_priority_min ()
	Get the minimum thread priority.

static int	get_priority_max ()
	Get the maximum thread priority.

Static Protected Member Functions inherited from LinkedObject< ExecutorBase >
static ExecutorBase *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Static Protected Attributes inherited from LinkedObject< ExecutorBase >
static ExecutorBase *	head_
	Beginning of the list.

Detailed Description

This class implements an execution of tasks pulled off an input queue.

Definition at line 63 of file Executor.hxx.

Constructor & Destructor Documentation

◆ ExecutorBase()

ExecutorBase::ExecutorBase ( )

Constructor.

Todo:: (Stuart Baker) is "name" still in use?

Definition at line 73 of file Executor.cxx.

◆ ~ExecutorBase()

ExecutorBase::~ExecutorBase ( )

Destructor.

Definition at line 455 of file Executor.cxx.

Member Function Documentation

◆ active_timers()

ActiveTimers * ExecutorBase::active_timers ( )

inline

Returns: the list of active timers.

Definition at line 144 of file Executor.hxx.

◆ add()

virtual void ExecutorBase::add	(	Executable *	action,
		unsigned	priority = `UINT_MAX`
	)

pure virtual

Send a message to this Executor's queue.

Parameters

action	Executable instance to insert into the input queue
priority	priority of execution

Implemented in Executor< NUM_PRIO >, Executor< 1 >, and Executor< EXECUTOR_PRIORITIES >.

◆ assert_current()

void ExecutorBase::assert_current ( )

inline

Die if we are not on the current executor.

Definition at line 160 of file Executor.hxx.

◆ by_name()

ExecutorBase * ExecutorBase::by_name	(	const char *	name,
		bool	wait
	)

static

Lookup an executor by its name.

Parameters

name	name of executor to lookup
wait	wait forever for an executor to show up

Returns: pointer to executor upon success, else NULL if not found

Parameters

name	name of executor to lookup

Returns: pointer to executor upon success, else NULL if not found

Todo:: (Stuart Baker) we need a locking mechanism here to protect the list.

Definition at line 90 of file Executor.cxx.

◆ current()

Executable * ExecutorBase::current ( )

inline

Helper function for debugging and tracing.

Returns: currently running executable or nullptr if none active.

Definition at line 168 of file Executor.hxx.

◆ empty()

virtual bool ExecutorBase::empty ( )

pure virtual

Returns: true if there are no executables waiting on this thread to be executed. There could still be a current executable.

Implemented in Executor< NUM_PRIO >, Executor< 1 >, and Executor< EXECUTOR_PRIORITIES >.

◆ entry()

void * ExecutorBase::entry ( )

overrideprotectedvirtual

Thread entry point.

Returns: Should never return

Reimplemented from OSThread.

Definition at line 293 of file Executor.cxx.

◆ get_select_set()

fd_set * ExecutorBase::get_select_set ( Selectable::SelectType type )

inlineprivate

Helper function.

Parameters

type	a select type: READ, WRITE or EXCEPT

Returns: the fd_set that's being waited for that given select type.

Definition at line 201 of file Executor.hxx.

◆ is_selected()

bool ExecutorBase::is_selected ( Selectable * job )

Returns: true if the given job's FD is currently enqueued for a select. This may or may not mean that the specific job is waiting for a select call. If this returns true, it does mean that trying to select() that job will cause a crash, since the same FD cannot be selected more than once.

Parameters

job	is the selectable to query.

Definition at line 352 of file Executor.cxx.

◆ loop_once()

bool ExecutorBase::loop_once ( )

Performs one loop of the execution on the calling thread.

Returns: true if there is more scheduled work to do. Returns false if the executor loop would block right now.

Definition at line 165 of file Executor.cxx.

◆ loop_some()

long long ICACHE_FLASH_ATTR ExecutorBase::loop_some ( )

Performs a few loops of the executor on the calling thread.

Returns: 0 if there is still pending work scheduled on the executor, non-zero if there is some work to do after a sleep. The returned value is the nanoseconds to sleep before calling loop_some again.

Definition at line 187 of file Executor.cxx.

◆ next()

virtual Executable * ExecutorBase::next ( unsigned * priority )

privatepure virtual

Retrieve an item from the front of the queue.

Parameters

priority pass back the priority of the queue pulled from

Returns: item retrieved from queue, else NULL if queue is empty.

Implemented in Executor< NUM_PRIO >, Executor< 1 >, and Executor< EXECUTOR_PRIORITIES >.

◆ run()

void ExecutorBase::run ( )

inlineoverrideprotectedvirtual

Entry point.

This funciton will be called when *this gets scheduled on the CPU.

Implements Executable.

Definition at line 176 of file Executor.hxx.

◆ select()

void ExecutorBase::select ( Selectable * job )

Adds a file descriptor to be watched to the select loop.

Parameters

job	Selectable structure that describes the descriptor to watch. The pointer must stay alive until it is activated, or is unselected.

Must be called on the executor thread.

Parameters

job	is a Selectable pointer that is not currently watched.

Definition at line 332 of file Executor.cxx.

◆ sequence()

virtual uint32_t ExecutorBase::sequence ( )

pure virtual

Returns: a number that gets incremented by one every time an executable runs.

Implemented in Executor< NUM_PRIO >, Executor< 1 >, and Executor< EXECUTOR_PRIORITIES >.

◆ shutdown()

void ExecutorBase::shutdown ( )

Terminates the executor thread.

Waits until it is safe to delete the executor.

Definition at line 437 of file Executor.cxx.

◆ sync_run()

void ExecutorBase::sync_run ( std::function< void()> fn )

Synchronously runs a closure on this executor.

Does not return until the execution is completed.

Parameters

fn	is the closure to run.

Definition at line 151 of file Executor.cxx.

◆ thread()

OSThread & ExecutorBase::thread ( )

inline

Definition at line 157 of file Executor.hxx.

◆ thread_handle()

os_thread_t ExecutorBase::thread_handle ( )

inline

Returns: the thread handle.

Definition at line 155 of file Executor.hxx.

◆ unselect()

void ExecutorBase::unselect ( Selectable * job )

Removes a job from the select loop.

This stops watching the given file descriptor. The job must have been previously inserted into the Executor and must be not yet activated.

Must be called on the executor thread.

Parameters

job	is a Selectable pointer that was previously inserted.

Definition at line 359 of file Executor.cxx.

◆ wait_with_select()

void ExecutorBase::wait_with_select ( long long next_timer_nsec )

private

Executes a select call, and schedules any necessary executables based on the return.

Will not sleep at all if not empty, otherwise sleeps at most next_timer_nsec nanoseconds (from now).

Parameters

next_timer_nsec is the maximum time to sleep in nanoseconds.

Definition at line 384 of file Executor.cxx.

Friends And Related Symbol Documentation

◆ Service

friend class Service

friend

provide access to Executor::send method.

Definition at line 247 of file Executor.hxx.

Member Data Documentation

◆ activeTimers_

ActiveTimers ExecutorBase::activeTimers_

private

List of active timers.

Definition at line 220 of file Executor.hxx.

◆ current_

Executable* volatile ExecutorBase::current_

private

Currently executing closure.

USeful for debugging crashes.

Definition at line 217 of file Executor.hxx.

◆ done_

std::atomic_uint_least8_t ExecutorBase::done_

private

Set to 1 when the executor thread has exited and it is safe to delete *this.

Definition at line 235 of file Executor.hxx.

◆ name_

const char* ExecutorBase::name_

private

name of this Executor

Definition at line 214 of file Executor.hxx.

◆ selectables_

TypedQueue<Selectable> ExecutorBase::selectables_

private

Head of the linked list for the select calls.

Definition at line 231 of file Executor.hxx.

◆ selectExcept_

fd_set ExecutorBase::selectExcept_

private

fd to select for except.

Definition at line 227 of file Executor.hxx.

◆ selectHelper_

OSSelectWakeup ExecutorBase::selectHelper_

protected

Helper object for interruptible select calls.

Definition at line 179 of file Executor.hxx.

◆ selectNFds_

int ExecutorBase::selectNFds_

private

maximum fd to select for + 1

Definition at line 229 of file Executor.hxx.

◆ selectPrescaler_

unsigned ExecutorBase::selectPrescaler_

private

How many executables we schedule blindly before calling a select() in order to find more data to read/write in the FDs being waited upon.

Definition at line 240 of file Executor.hxx.

◆ selectRead_

fd_set ExecutorBase::selectRead_

private

fd to select for read.

Definition at line 223 of file Executor.hxx.

◆ selectWrite_

fd_set ExecutorBase::selectWrite_

private

fd to select for write.

Definition at line 225 of file Executor.hxx.

◆ sequence_

volatile unsigned ExecutorBase::sequence_

protected

Sequence number.

Definition at line 244 of file Executor.hxx.

◆ started_

std::atomic_uint_least8_t ExecutorBase::started_

private

1 if the executor is already running

Definition at line 237 of file Executor.hxx.

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ExecutorBase()

◆ ~ExecutorBase()

Member Function Documentation

◆ active_timers()

◆ add()

◆ assert_current()

◆ by_name()

◆ current()

◆ empty()

◆ entry()

◆ get_select_set()

◆ is_selected()

◆ loop_once()

◆ loop_some()

◆ next()

◆ run()

◆ select()

◆ sequence()

◆ shutdown()

◆ sync_run()

◆ thread()

◆ thread_handle()

◆ unselect()

◆ wait_with_select()

Friends And Related Symbol Documentation

◆ Service

Member Data Documentation

◆ activeTimers_

◆ current_

◆ done_

◆ name_

◆ selectables_

◆ selectExcept_

◆ selectHelper_

◆ selectNFds_

◆ selectPrescaler_

◆ selectRead_

◆ selectWrite_

◆ sequence_

◆ started_