A periodic task, implementing a microthread. More...

#include <Process.h>

Inheritance diagram for mel::tasking::Process:

Public Types
enum	EProcessState : uint8_t { PREPARED , INITIATED , ASLEEP , PREPARED_TO_DIE , TRYING_TO_KILL , KILLING_WAITING_FOR_SCHEDULED , DEAD }

enum class	ESwitchResult { ESWITCH_OK , ESWITCH_WAKEUP , ESWITCH_ERROR , ESWITCH_KILL }
	Reason why the process returns from context switch. More...

Public Member Functions
	Process (unsigned short capacity=0)
	constructor More...

void	setProcessScheduler (ProcessScheduler *const mgr)
	Sets ProcessScheduler which holds this process. Each process can only be scheduled by one ProcessScheduler.

void	pause ()
	pause execution until wakeup called onPause is called in order children can do custom behaviour

void	kill (bool force=false)
	Mark this process to be eliminated by the process manager. More...

virtual void	reset ()
	Sets process in init state.

void	setPeriod (unsigned int value)
	Set the period for this process. More...

EProcessState	getState () const

bool	getDead () const

unsigned int	getPeriod () const
	get period (milliseconds) More...

unsigned int	getElapsedTime () const

uint64_t	getLastUpdateTime () const

void	resetTime ()

ProcessScheduler *const	getProcessScheduler () const
	Gets ProcessScheduler which holds this Process.

bool	getAsleep () const

void	wakeUp ()
	wakeup an asleep process or an evicted process (that process having called swtich or wait)

Static Public Member Functions
static ESwitchResult	wait (unsigned int msegs) OPTIMIZE_FLAGS

static ESwitchResult	switchProcess (bool continueInmediately) OPTIMIZE_FLAGS
	Evict current process and will continue executing from the same point the next time is scheduled. More...

template<class F >
static ESwitchResult	sleepAndDo (F postSleep)
	Sleep current process and execute given callable. To reactivate to you must use wakeUp. More...

template<class F >
static ESwitchResult	waitAndDo (unsigned int msegs, F postWait) OPTIMIZE_FLAGS
	Wait for a given time and execute given callable. More...

static ESwitchResult	sleep () OPTIMIZE_FLAGS
	pause current process. To reactivate you must use wakeUp More...

Protected Member Functions
virtual void	onUpdate (uint64_t msecs)=0

virtual void	onInit (uint64_t msecs)

virtual bool	onKill ()

virtual void	onPause ()
	Called when a process is paused.

virtual void	onWakeUp ()
	Called when process is woken up.

virtual void	killDone ()

Friends
class	ProcessScheduler

Detailed Description

A periodic task, implementing a microthread.

Once the process is inserted in a mel::tasking::ProcessScheduler (usually done through a Runnable via mel::tasking::Runnable::post or mel::tasking::Runnable::execute) the update() (private) member function will be called. because this class is abstract, a concrete Process must implement the function onUpdate function to code its custom behaviour. The task will be executed as time intervals, given by the period (getPeriod) until is killed (see kill)

Remarks: Tasks are executed according to a Timer, which uses uint64_t type to express msecs, but for eficiency reasons using a 64 bits type on 32 bits machines will be very "agressive", so we use unsigned int as time for tasks so getting the low part of the original 64 bit time and hoping it will be enough...; Switching a Process inside a try/catch context doesn't fit very well with exception handling for this context. This issue is being addressed... If this fact is carefully considered when doing "switchs" it will not be a problem, but in Windows (maybe other Operating Systems?) there is a exploitation prevent system (called SEHOP, see https://blogs.technet.microsoft.com/srd/2009/02/02/preventing-the-exploitation-of-structured-exception-handler-seh-overwrites-with-sehop/) )that will make the app crash because Windows interpret it as a hack process. This option is disabled in worksations but enabled for Windows Server- To disable it, go to HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control/Session Manager/Kernel/DisableExceptionChainValidation

Member Enumeration Documentation

◆ EProcessState

enum mel::tasking::Process::EProcessState : uint8_t

Enumerator
PREPARED	Process created but not executed.
INITIATED	executing process normally
ASLEEP	sleeping. Waiting for a wakeup
PREPARED_TO_DIE	it's going to die, but process manager doesn't discard it yet
TRYING_TO_KILL	sending kill signal but no accepted yet
KILLING_WAITING_FOR_SCHEDULED	switched and no shceduled yet
DEAD	process is out of process manager

◆ ESwitchResult

enum mel::tasking::Process::ESwitchResult

strong

Reason why the process returns from context switch.

Enumerator
ESWITCH_OK	return from context switch was ok
ESWITCH_WAKEUP	return from context switch was because a wakeup
ESWITCH_ERROR	switch couldn't be done
ESWITCH_KILL	return from context switch because a kill

Constructor & Destructor Documentation

◆ Process()

mel::tasking::Process::Process ( unsigned short capacity = 0 )

constructor

Parameters

capacity Initial stack capacity,in bytes. A value of 0 means no stack precreated. In any case, stack grows as needed

Member Function Documentation

◆ getDead()

bool mel::tasking::Process::getDead ( ) const

inline

check if process is dead

◆ getElapsedTime()

unsigned int mel::tasking::Process::getElapsedTime ( ) const

returns time elapsed during this iteration

◆ getLastUpdateTime()

uint64_t mel::tasking::Process::getLastUpdateTime ( ) const

inline

Returns: time when task was executed in last iteration, when onUpdate is called:

Note: context switches or waits inside code doesn't modify update time.

◆ getPeriod()

unsigned int mel::tasking::Process::getPeriod ( ) const

inline

get period (milliseconds)

check if process is going to die

◆ kill()

void mel::tasking::Process::kill ( bool force = false )

Mark this process to be eliminated by the process manager.

Internally, kill calls virtual function Process::onKill, which returns true if kill can be acomplished or not. In case of true, then process is put in PREPARED_TO_DIE state, so the scheduler can remove it. In case of false, process is put in a TRYING_TO_KILL state so scheduler will continue to trying to kill it in next iterations. You can know if a process is die checking getDead

Remarks: if process is not already inited (state == PREPARED) then onKill is not called

Parameters

[in] force if true, then killing is without regarding previous explained process, so Process go inmediately to PREPARED_TO_DIE

Remarks: not multithread safe, kill should be done in the owner thread context (se abordar� en el futuro)

◆ killDone()

virtual void mel::tasking::Process::killDone ( )

inlineprotectedvirtual

called when kill is definitively done

◆ onInit()

virtual void mel::tasking::Process::onInit ( uint64_t msecs )

inlineprotectedvirtual

called when process inits

Parameters

msecs milliseconds

Reimplemented in mel::tasking::GenericProcess.

◆ onKill()

virtual bool mel::tasking::Process::onKill ( )

inlineprotectedvirtual

called when process is going to be got out of scheduler and was inited (not in PREPARED state) can be overridden by children

Returns: bool. True if kill can be acomplished

Remarks: it's only called when kill is called with force = false

Reimplemented in mel::tasking::GenericProcess.

◆ onUpdate()

virtual void mel::tasking::Process::onUpdate ( uint64_t msecs )

protectedpure virtual

behaviour function. The main function of a process. MUST be implemented in childs. It's called automatically when elapsed time >= mPeriod

Parameters

msecs milliseconds

Implemented in mel::tasking::GenericProcess.

◆ setPeriod()

void mel::tasking::Process::setPeriod ( unsigned int value )

inline

Set the period for this process.

Parameters

value the new period (in msecs)

◆ sleep()

static ESwitchResult mel::tasking::Process::sleep ( )

static

pause current process. To reactivate you must use wakeUp

Returns: true if process received kill signal

See also: switchProcess for comments

◆ sleepAndDo()

template<class F >

Process::ESwitchResult mel::tasking::Process::sleepAndDo ( F postSleep )

static

Sleep current process and execute given callable. To reactivate to you must use wakeUp.

Parameters

[in] postSleep functor (signature void(void) ) to execute just in the moment when Process go to sleep

Returns: resulting state of these operation

See also: sleep

Remarks: not multithread-safe

◆ switchProcess()

static ESwitchResult mel::tasking::Process::switchProcess ( bool continueInmediately )

static

Evict current process and will continue executing from the same point the next time is scheduled.

this function is a static one because, in the same way threads work, is the currently executing process which can be evicted in any point of the execution call stack.

Parameters

continueInmediately if true, the process will continue executing in the next shceduler cycle, so without respecting the period.

◆ wait()

static ESwitchResult mel::tasking::Process::wait ( unsigned int msegs )

static

Returns: true if process received kill signal

See also: switchProcess for comments

◆ waitAndDo()

template<class F >

Process::ESwitchResult mel::tasking::Process::waitAndDo	(	unsigned int	msegs,
		F	postWait
	)

static

Wait for a given time and execute given callable.

Parameters

[in] postWait functor (signature <void,void>) to execute just in the moment when Process go to sleep

Returns: resulting state of the operation

See also: sleep

Remarks: not multithread-safe

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

/github/workspace/mel/include/tasking/Process.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ EProcessState

◆ ESwitchResult

Constructor & Destructor Documentation

◆ Process()

Member Function Documentation

◆ getDead()

◆ getElapsedTime()

◆ getLastUpdateTime()

◆ getPeriod()

◆ kill()

◆ killDone()

◆ onInit()

◆ onKill()

◆ onUpdate()

◆ setPeriod()

◆ sleep()

◆ sleepAndDo()

◆ switchProcess()

◆ wait()

◆ waitAndDo()