OSDL::Engine::PeriodicalActiveObject Class Reference

Periodical active objects are active objects that are to be scheduled at a regular pace: for an object whose period is N, the scheduler is expected to trigger it every N of its fundamental simulation ticks. More...

#include <OSDLPeriodicalActiveObject.h>

Inheritance diagram for OSDL::Engine::PeriodicalActiveObject:

[legend]

Collaboration diagram for OSDL::Engine::PeriodicalActiveObject:

[legend]

List of all members.

Public Member Functions
	PeriodicalActiveObject (Ceylan::System::Millisecond periodDuration, bool autoRegister=true, Ceylan::Maths::Percentage maxErrorPercentage=5)
	Constructor of a periodically activated object, which will be activated with the specified period, expressed directly as a duration in user time, not as a number of scheduling ticks.
	PeriodicalActiveObject (Events::Period period, bool autoRegister, ObjectSchedulingPolicy policy, Weight weight)
	Constructor of a periodically activated object.
virtual	~PeriodicalActiveObject () throw ()
	Virtual destructor.
virtual void	registerToScheduler ()
	Registers this active object to the supposedly already existing scheduler.
virtual void	unregisterFromScheduler ()
	Unregisters this active object from the existing scheduler to whom it was supposedly registered.
virtual Events::Period	getPeriod () const
	Returns the period for this active object.
virtual void	setPeriod (Events::Period newPeriod)
	Sets a period for this object, which will be periodically scheduled accordingly.
virtual Ceylan::Maths::Hertz	setFrequency (Ceylan::Maths::Hertz newFrequency)
	Sets the period of this object so that it gets activated on specified frequency, making this object periodically activated if it was not, or changing its already defined period otherwise.
virtual Events::Period	getSubslotNumber () const
	Returns the number of the sub-slot this active object is referenced in.
virtual void	onRegistering (Events::Period subslot)
	Automatically called by the scheduler at registration time.
virtual void	setBirthTick (Events::SimulationTick currentSimulationTick)
	Sets the birth time, expressed in simulation ticks, of this active object.
virtual Events::SimulationTick	convertDurationToActivationCount (Ceylan::System::Millisecond duration) const
	Returns the number of activations of this periodical object which corresponds to the specified duration.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns a user-friendly description of the state of this object.
virtual ObjectSchedulingPolicy	getPolicy () const
	Returns the scheduling policy for this active object.
virtual Weight	getWeight () const
	Returns the average processing need for each activation of this object.
virtual Events::SimulationTick	getBirthTick () const
	Returns the birth time, expressed in simulation ticks, of this active object.
virtual void	onActivation (Events::SimulationTick newTick)=0
	Pure virtual method, which is called when this active object gets activated on behalf of the scheduler.
virtual void	onSkip (Events::SimulationTick skippedTick)
	Called whenever the scheduler had to skip a period of activation for this object.
virtual void	onImpossibleActivation (Events::SimulationTick missedTick)
	Called whenever the scheduler was unable to activate this object.
Protected Member Functions
Events::SimulationTick	getLocalTime () const
	Returns this object local time, as if the origin of time was this object creation.
Protected Attributes
Events::Period	_period
	Tells what is the requested scheduling period for this object.
Events::Period	_subslot
	Records in which sub-slot this object is stored.
ObjectSchedulingPolicy	_policy
	Determines the scheduling policy of this object.
Weight	_weight
	Describe the average processing need for each activation of this object.
bool	_registered
	Tells whether this active object has already been registered to a scheduler.
Events::SimulationTick	_birthTick
	The date of birth of this object, expressed in simulation time.

Detailed Description

Periodical active objects are active objects that are to be scheduled at a regular pace: for an object whose period is N, the scheduler is expected to trigger it every N of its fundamental simulation ticks.

Therefore a periodical object can run at any frequency that is a submultiple of the scheduler fundamental one.

The scheduler tries to balance the activation of the periodical objects sharing the same period. For example, objects whose period is 7 are stored in the slot dedicated to the period 7, which has 7 sub-slots in which all these objects tend to be evenly dispatched.

Therefore every simulation tick one of these sub-slots will be scheduled (approximately 1/7 of the objects of period 7 will therefore be activated), and the next simulation tick the next sub-slot will be scheduled, etc.

At the end, all objects will be scheduled at their requested frequency, and their scheduling should be relatively balanced, from a simulation tick to another.

Note that this scattering will not decrease the number of idle calls that can be performed, as they are to take place between simulation ticks, which will be scheduled regardless of whether there is a periodical object to activate.

The birth time of an active object is the first time when it is registered and when the scheduler runs (this can happen in any order). For example it is not the tick corresponding to the first time this periodical object is activated.

See also:: also the ProgrammedActiveObject class.

Definition at line 90 of file OSDLPeriodicalActiveObject.h.

Constructor & Destructor Documentation

PeriodicalActiveObject::PeriodicalActiveObject	(	Ceylan::System::Millisecond	periodDuration,
		bool	autoRegister = `true`,
		Ceylan::Maths::Percentage	maxErrorPercentage = `5`
	)			`[explicit]`

Constructor of a periodically activated object, which will be activated with the specified period, expressed directly as a duration in user time, not as a number of scheduling ticks.

Parameters:

	periodDuration	tells how many actual milliseconds should elapse until two activations of the created object. The period must not be null.
	autoRegister	the created object will automatically register to the scheduler iff true.
	maxErrorPercentage	its the maximal percentage of tolerated error between the requested period duration and the actual one (they may differ to the granularity of scheduling ticks).

Returns:: the corresponding created periodical object.

Exceptions:

SchedulingException

if the construction failed.

Note:: Not a constructor to avoid two similar constructor signatures.

Definition at line 53 of file OSDLPeriodicalActiveObject.cc.

References _period, OSDL::Engine::Scheduler::GetExistingScheduler(), OSDL::Engine::Scheduler::getSimulationTickCount(), OSDL::Engine::Scheduler::getTimeSliceDuration(), registerToScheduler(), and OSDL::Video::Pixels::toString().

OSDL::Engine::PeriodicalActiveObject::PeriodicalActiveObject	(	Events::Period	period,
		bool	autoRegister,
		ObjectSchedulingPolicy	policy,
		Weight	weight
	)

Constructor of a periodically activated object.

Parameters:

	period	tells how many simulation steps are to be waited by the scheduler until this active object is activated again. The period must not be null.
	autoRegister	this object will automatically register to the scheduler iff true.
	policy	allows to choose a scheduling policy, according to the quality of service this active object requires.
	weight	evaluates how much processing power an activation of this object is to cost, on average. This helps the scheduler doing its job.

Exceptions:

SchedulingException

if the construction failed.

Note:: No parameter has a default value so that no ambiguity exists with the other constructor.

PeriodicalActiveObject::~PeriodicalActiveObject ( ) throw () [virtual]

Virtual destructor.

Note:: This object will automatically unsubscribe from the scheduler if needed.

Definition at line 121 of file OSDLPeriodicalActiveObject.cc.

References OSDL::Engine::ActiveObject::_registered, and unregisterFromScheduler().

Member Function Documentation

OSDL::Events::SimulationTick PeriodicalActiveObject::convertDurationToActivationCount ( Ceylan::System::Millisecond duration ) const [virtual]

Returns the number of activations of this periodical object which corresponds to the specified duration.

For example a duration of 400 ms, for a periodical object whose period is 50 ms, corresponds to 8 of its simulation ticks.

Parameters:

duration

Exceptions:

SchedulingException

if the operation failed, notably if this object is not stored in a sub-slot already.

Definition at line 340 of file OSDLPeriodicalActiveObject.cc.

References _period, OSDL::Engine::Scheduler::GetExistingScheduler(), OSDL::Engine::Scheduler::getSimulationTickCount(), and OSDL::Engine::Scheduler::getTimeSliceDuration().

SimulationTick ActiveObject::getBirthTick ( ) const [virtual, inherited]

Returns the birth time, expressed in simulation ticks, of this active object.

Definition at line 107 of file OSDLActiveObject.cc.

References OSDL::Engine::ActiveObject::_birthTick.

Referenced by OSDL::Engine::Scheduler::unregisterProgrammedObject().

Events::SimulationTick OSDL::Engine::ActiveObject::getLocalTime ( ) const [protected, inherited]

Returns this object local time, as if the origin of time was this object creation.

Period PeriodicalActiveObject::getPeriod ( ) const [virtual]

Returns the period for this active object.

Definition at line 194 of file OSDLPeriodicalActiveObject.cc.

References _period.

Referenced by OSDL::Engine::Scheduler::registerPeriodicalObject(), and OSDL::Engine::Scheduler::unregisterPeriodicalObject().

ObjectSchedulingPolicy ActiveObject::getPolicy ( ) const [virtual, inherited]

Returns the scheduling policy for this active object.

Definition at line 80 of file OSDLActiveObject.cc.

References OSDL::Engine::ActiveObject::_policy.

Referenced by OSDL::Engine::PeriodicSlot::add().

Period PeriodicalActiveObject::getSubslotNumber ( ) const [virtual]

Returns the number of the sub-slot this active object is referenced in.

This sub-slot is set on registration: the scheduler calls the onRegistering method of this object.

Exceptions:

SchedulingException

if the operation failed, notably if this object is not stored in a sub-slot already.

Definition at line 271 of file OSDLPeriodicalActiveObject.cc.

References _period, and _subslot.

Weight ActiveObject::getWeight ( ) const [virtual, inherited]

Returns the average processing need for each activation of this object.

Note:: The greater the weight is, the heavier processing should be.

Definition at line 89 of file OSDLActiveObject.cc.

References OSDL::Engine::ActiveObject::_weight.

virtual void OSDL::Engine::ActiveObject::onActivation ( Events::SimulationTick newTick ) [pure virtual, inherited]

Pure virtual method, which is called when this active object gets activated on behalf of the scheduler.

Note:: This is where the objects are to live actually: their time slice is to be spent here.; If, for any reason, there is a simulation skip, this method may not be called for some objects. Refer to the onSkip method, which would be called instead (and, sadly, later).

See also:: onSkip.

virtual void OSDL::Engine::ActiveObject::onImpossibleActivation ( Events::SimulationTick missedTick ) [virtual, inherited]

Called whenever the scheduler was unable to activate this object.

This can happen for example when an absolute simulation tick is specified whereas the current time is already in its future.

Default behaviour for this method is: throw a SchedulingException.

Parameters:

missedTick

tells which tick is out of range.

Exceptions:

SchedulingException

if this active object should not stand activation failures.

void PeriodicalActiveObject::onRegistering ( Events::Period subslot ) [virtual]

Automatically called by the scheduler at registration time.

Sets the sub-slot, to ease deallocation.

Note:: Registering does not always imply object birth, as if the scheduler is not currently running, then birth will happen only when it is started.

Exceptions:

SchedulingException

if the operation failed.

Definition at line 284 of file OSDLPeriodicalActiveObject.cc.

References OSDL::Engine::ActiveObject::_registered, and _subslot.

Referenced by OSDL::Engine::Scheduler::registerPeriodicalObject().

virtual void OSDL::Engine::ActiveObject::onSkip ( Events::SimulationTick skippedTick ) [virtual, inherited]

Called whenever the scheduler had to skip a period of activation for this object.

Default behaviour for this method is: do nothing except complain in the warning channel.

Parameters:

skippedTick

tells which tick was skipped.

Exceptions:

SchedulingException

if this active object cannot stand skipped stimulation ticks.

Note:: Some objects may call the onActivation method for the skipped tick, to emulate the behaviour they would have had if they could have been scheduled at the right time.

void PeriodicalActiveObject::registerToScheduler ( ) [virtual]

Registers this active object to the supposedly already existing scheduler.

Exceptions:

SchedulingException

if the operation failed.

Implements OSDL::Engine::ActiveObject.

Definition at line 152 of file OSDLPeriodicalActiveObject.cc.

References OSDL::Engine::ActiveObject::_registered, OSDL::Engine::Scheduler::GetExistingScheduler(), and OSDL::Engine::Scheduler::registerPeriodicalObject().

Referenced by PeriodicalActiveObject().

void PeriodicalActiveObject::setBirthTick ( Events::SimulationTick currentSimulationTick ) [virtual]

Sets the birth time, expressed in simulation ticks, of this active object.

Note:: Called by the scheduler, when registering this active object. This object will compute its exact actual begin tick, depending on the sub-slot it has been put in.

Exceptions:

SchedulingException

if the operation failed.

Reimplemented from OSDL::Engine::ActiveObject.

Definition at line 301 of file OSDLPeriodicalActiveObject.cc.

References OSDL::Engine::ActiveObject::_birthTick, _period, and _subslot.

Referenced by OSDL::Engine::Scheduler::registerPeriodicalObject().

virtual Ceylan::Maths::Hertz OSDL::Engine::PeriodicalActiveObject::setFrequency ( Ceylan::Maths::Hertz newFrequency ) [virtual]

Sets the period of this object so that it gets activated on specified frequency, making this object periodically activated if it was not, or changing its already defined period otherwise.

Parameters:

newFrequency

the desired frequency, expressed in Hertz.

Returns:: The actual chosen frequency, which may differ a bit from specified one since it depends on the simulation tick granularity. Notably, the obtained frequency cannot exceed the specified simulation frequency for the scheduler. The actual frequency is nevertheless chosen as the nearest possible frequency.

Note:: To be able to compute the actual period, expressed in simulation ticks, from the specified frequency, the scheduler that will be later used for this object is needed.

Exceptions:

SchedulingException

if there was no existing scheduler available.

virtual void OSDL::Engine::PeriodicalActiveObject::setPeriod ( Events::Period newPeriod ) [virtual]

Sets a period for this object, which will be periodically scheduled accordingly.

Parameters:

newPeriod

the new period of activation for this object, expressed in simulation ticks. Must be strictly positive.

Exceptions:

SchedulingException

if the operation failed.

const string PeriodicalActiveObject::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Reimplemented from OSDL::Engine::ActiveObject.

Reimplemented in OSDL::MVC::PeriodicalModel.

Definition at line 356 of file OSDLPeriodicalActiveObject.cc.

References _period, and _subslot.

void PeriodicalActiveObject::unregisterFromScheduler ( ) [virtual]

Unregisters this active object from the existing scheduler to whom it was supposedly registered.

Exceptions:

SchedulingException

if the operation failed.

Implements OSDL::Engine::ActiveObject.

Definition at line 169 of file OSDLPeriodicalActiveObject.cc.

References OSDL::Engine::ActiveObject::_registered, OSDL::Engine::Scheduler::GetExistingScheduler(), and OSDL::Engine::Scheduler::unregisterPeriodicalObject().

Referenced by ~PeriodicalActiveObject().

Member Data Documentation

Events::SimulationTick OSDL::Engine::ActiveObject::_birthTick [protected, inherited]

The date of birth of this object, expressed in simulation time.

Note:: the date of birth corresponds to the first future simulation tick this object is known for the running scheduler (either the scheduler start-up, if this object was registered before), or the simulation tick at which this object was dynamically registered to the scheduler.

Definition at line 373 of file OSDLActiveObject.h.

Referenced by OSDL::Engine::ActiveObject::getBirthTick(), setBirthTick(), and OSDL::Engine::ActiveObject::toString().

Events::Period OSDL::Engine::PeriodicalActiveObject::_period [protected]

Tells what is the requested scheduling period for this object.

Definition at line 355 of file OSDLPeriodicalActiveObject.h.

Referenced by convertDurationToActivationCount(), getPeriod(), getSubslotNumber(), PeriodicalActiveObject(), setBirthTick(), and toString().