OSDL::Engine::ProgrammedActiveObject Class Reference

Programmed active objects are objects that are to be scheduled in at specific simulation ticks, as opposed to periodically activated ones. More...

#include <OSDLProgrammedActiveObject.h>

Inheritance diagram for OSDL::Engine::ProgrammedActiveObject:

[legend]

Collaboration diagram for OSDL::Engine::ProgrammedActiveObject:

[legend]

List of all members.

Public Member Functions
	ProgrammedActiveObject (const SimulationTickList &activationTicks, bool absolutelyDefined=true, bool autoRegister=true, ObjectSchedulingPolicy policy=relaxed, Weight weight=1)
	Constructor of an object activated only on specifically programmed simulation ticks.
	ProgrammedActiveObject (Events::SimulationTick activationTick, bool absolutelyDefined=true, bool autoRegister=false, ObjectSchedulingPolicy policy=relaxed, Weight weight=1)
	Constructor of an object activated only on a specific simulation tick (one-shot, as opposed to a list).
virtual	~ProgrammedActiveObject () 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.
bool	areProgrammedActivationsAbsolute () const
	Tells whether programmed activations are defined absolutely (from the origin of simulation times, i.e.
void	absoluteProgrammedActivationsWanted (bool on)
	Defines whether the programmed activations for this object are to be defined absolutely (from the origin of simulation times, i.e.
virtual const SimulationTickList &	getProgrammedActivations () const
	Returns a reference to the internal list of programmed activations of this object.
virtual void	setProgrammedActivations (const SimulationTickList &newActivationsList)
	Sets the list of programmed activations for this object to specified value.
virtual void	addProgrammedActivations (const SimulationTickList &additionalActivationsList)
	Adds the specified list of simulation ticks to the list of activation ticks for this object.
virtual void	onRegistering ()
	Automatically called by the scheduler at registration time.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an 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	setBirthTick (Events::SimulationTick currentSimulationTick)
	Sets 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
SimulationTickList	_programmedTicks
	Records the list of programmed simulation ticks that will be used by the scheduler to activate this object.
bool	_absoluteTicks
	Tells whether the programmed trigger ticks should be understood as absolute (i.e.
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

Programmed active objects are objects that are to be scheduled in at specific simulation ticks, as opposed to periodically activated ones.

Thus programmed objects define a list of simulation ticks at which they should be scheduled. These ticks can be specified as absolute times or as offsets, i.e. relatively to the simulation tick they were registered.

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 programmed object is activated.

See also:: also the PeriodicalActiveObject class.

Definition at line 71 of file OSDLProgrammedActiveObject.h.

Constructor & Destructor Documentation

ProgrammedActiveObject::ProgrammedActiveObject	(	const SimulationTickList &	activationTicks,
		bool	absolutelyDefined = `true`,
		bool	autoRegister = `true`,
		ObjectSchedulingPolicy	policy = `relaxed`,
		Weight	weight = `1`
	)			`[explicit]`

Constructor of an object activated only on specifically programmed simulation ticks.

Parameters:

	activationTicks	is the list of simulation ticks when this object should be activated. This object does not take ownership of this list, it will make a copy of it.
	absolutelyDefined	tells whether the specified ticks are defined absolutely, or relatively to the simulation tick at which this object will be registered to the scheduler.
	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.

Definition at line 49 of file OSDLProgrammedActiveObject.cc.

References _programmedTicks, and registerToScheduler().

ProgrammedActiveObject::ProgrammedActiveObject	(	Events::SimulationTick	activationTick,
		bool	absolutelyDefined = `true`,
		bool	autoRegister = `false`,
		ObjectSchedulingPolicy	policy = `relaxed`,
		Weight	weight = `1`
	)			`[explicit]`

Constructor of an object activated only on a specific simulation tick (one-shot, as opposed to a list).

Parameters:

	activationTick	is the simulation tick when this object should be activated.
	absolutelyDefined	tells if the specified tick is defined absolutely, or relatively to the current simulation tick.
	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.

Definition at line 70 of file OSDLProgrammedActiveObject.cc.

References _programmedTicks, and registerToScheduler().

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

Virtual destructor.

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

Definition at line 90 of file OSDLProgrammedActiveObject.cc.

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

Member Function Documentation

void ProgrammedActiveObject::absoluteProgrammedActivationsWanted ( bool on )

Defines whether the programmed activations for this object are to be defined absolutely (from the origin of simulation times, i.e.

the scheduler start) or relatively to the simulation tick of the object registering to the scheduler.

Exceptions:

SchedulingException

if the operation failed.

Definition at line 181 of file OSDLProgrammedActiveObject.cc.

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

void ProgrammedActiveObject::addProgrammedActivations ( const SimulationTickList & additionalActivationsList ) [virtual]

Adds the specified list of simulation ticks to the list of activation ticks for this object.

Parameters:

additionalActivationsList

the list of additional simulation ticks on which this object will be activated too.

Note:: The method will ensure that this object will not be activated more than once on any given simulation tick.; Scheduling settings should not be changed once an active object has been registered to the scheduler, as the list has already been transmitted to it.

Exceptions:

SchedulingException

if the operation failed.

Definition at line 220 of file OSDLProgrammedActiveObject.cc.

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

bool ProgrammedActiveObject::areProgrammedActivationsAbsolute ( ) const

Tells whether programmed activations are defined absolutely (from the origin of simulation times, i.e.

the scheduler start) or relatively to the simulation tick of the object registering to the scheduler.

Definition at line 172 of file OSDLProgrammedActiveObject.cc.

References _absoluteTicks.

Referenced by OSDL::Engine::Scheduler::registerProgrammedObject(), and OSDL::Engine::Scheduler::unregisterProgrammedObject().

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.

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().

const SimulationTickList & ProgrammedActiveObject::getProgrammedActivations ( ) const [virtual]

Returns a reference to the internal list of programmed activations of this object.

These are the activations as they were specified: if they were relative ticks, they are still offsets, not absolute times.

Definition at line 195 of file OSDLProgrammedActiveObject.cc.

References _programmedTicks.

Referenced by OSDL::Engine::Scheduler::registerProgrammedObject(), and OSDL::Engine::Scheduler::unregisterProgrammedObject().

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 ProgrammedActiveObject::onRegistering ( ) [virtual]

Automatically called by the scheduler at registration time.

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 245 of file OSDLProgrammedActiveObject.cc.

References OSDL::Engine::ActiveObject::_registered.

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

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 ProgrammedActiveObject::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 121 of file OSDLProgrammedActiveObject.cc.

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

Referenced by ProgrammedActiveObject().

virtual void OSDL::Engine::ActiveObject::setBirthTick ( Events::SimulationTick currentSimulationTick ) [virtual, inherited]

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

Note:: Called by the scheduler, when registering this active object.

Exceptions:

SchedulingException

if the operation failed.

Reimplemented in OSDL::Engine::PeriodicalActiveObject.

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

void ProgrammedActiveObject::setProgrammedActivations ( const SimulationTickList & newActivationsList ) [virtual]

Sets the list of programmed activations for this object to specified value.

Parameters:

newActivationsList

the list of simulation ticks which will be copied internally.

Note:: Any previously defined activations are lost.; Scheduling settings should not be changed once an active object has been registered to the scheduler, as the list has already been transmitted to it.

See also:: addProgrammedActivations.

Exceptions:

SchedulingException

if the operation failed.

Definition at line 205 of file OSDLProgrammedActiveObject.cc.

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

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

Returns an 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::ProgrammedModel.

Definition at line 254 of file OSDLProgrammedActiveObject.cc.

References _absoluteTicks, and _programmedTicks.

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

void ProgrammedActiveObject::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 146 of file OSDLProgrammedActiveObject.cc.

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

Referenced by ~ProgrammedActiveObject().

Member Data Documentation

bool OSDL::Engine::ProgrammedActiveObject::_absoluteTicks [protected]

Tells whether the programmed trigger ticks should be understood as absolute (i.e.

if their simulation ticks should be taken litteraly), or as relative (defined as an offset from this object birth time).

Is true by default.

Definition at line 347 of file OSDLProgrammedActiveObject.h.

Referenced by absoluteProgrammedActivationsWanted(), areProgrammedActivationsAbsolute(), and toString().

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(), OSDL::Engine::PeriodicalActiveObject::setBirthTick(), and OSDL::Engine::ActiveObject::toString().

ObjectSchedulingPolicy OSDL::Engine::ActiveObject::_policy [protected, inherited]

Determines the scheduling policy of this object.

Definition at line 338 of file OSDLActiveObject.h.

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

SimulationTickList OSDL::Engine::ProgrammedActiveObject::_programmedTicks [protected]

Records the list of programmed simulation ticks that will be used by the scheduler to activate this object.