OSDL: OSDL::Engine::ActiveObject Class Reference

which needs some CPU time, since they live. They are therefore taken into account by our scheduler, which applies simple heuristics so that each active object is granted with the processing power it requested, on a best-effort basis, according to an appropriate timing.

These objects can be activated on a regular basis, a period being specified for them, or on specific simulation steps. In this case, a list of simulation steps is to be specified, absolutely or relatively to the current simulation step. An object can be activated on a periodic basis, as a programmed object, or both.

An active object can be implemented according to one of the two classic approaches. For a given simulation time n, the object behaviour can be computed : 1. only from the current simulation time, n 2. from the state of the object as it was on simulation time (n-1), and maybe other parameters.

The best approach is the first, since a failure to process time n can be corrected in time (n+1), whereas the second approach demands all simulation steps to be processed and therefore would not allow the scheduler in the hurry to skip any step. However, not all behaviours could follow the first approach.

An example of a successful first approach would be a windmill turning at a constant rate, therefore registered as an active object with periodic scheduling. The second approach would define the new angle of its wheel as the previous angle, plus the angular speed times the duration between two simulation ticks. The recommended first approach would be to compute the wheel angle from its initial time and position, and turn it from the angular speed times the simulation time elapsed since the birth of this active object. Alas, not all behaviours can follow the first approach. For the corresponding unfortunate objects, there is however a last chance to correct a simulation skip : the scheduler will call their onSkip method, which may be used to overcome such scheduling hiccups.

Definition at line 80 of file OSDLActiveObject.h.


Public Types
typedef std::list< Events::SimulationTick >	SimulationTickList
	Types for lists of simulation ticks.
Public Member Functions
	ActiveObject (Events::Period period=1, ObjectSchedulingPolicy policy=relaxed, Weight weight=1) throw ()
	Constructor of a periodically activated object.
	ActiveObject (const SimulationTickList &triggeringStates, bool absolutlyDefined=true, ObjectSchedulingPolicy policy=relaxed, Weight weight=1) throw ()
	Constructor of a object activated only on specifically programmed simulation steps.
	ActiveObject (Events::SimulationTick triggerTick, bool absolutlyDefined, ObjectSchedulingPolicy policy=relaxed, Weight weight=1) throw ()
	Constructor of a object activated only on a specific simulation step.
virtual	~ActiveObject () throw ()
	Virtual destructor, which performs automatic unsubscribing of this object from the scheduler.
virtual ObjectSchedulingPolicy	getPolicy () const throw ()
	Returns the scheduling policy for this active object.
virtual Weight	getWeight () const throw ()
	Returns the average processing need for each activation of this object.
virtual Events::Period	getPeriod () const throw ()
	Returns the period for this active object.
virtual void	setPeriod (Events::Period newPeriod) throw ()
	Sets a period for this object, which will be periodically scheduled accordingly.
virtual Events::Hertz	setFrequency (Events::Hertz newFrequency) throw ( SchedulingException )
	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 bool	hasProgrammedActivations () const throw ()
	Tells whether this object has programmed activations set.
bool	areProgrammedActivationsAbsolute () const throw ()
	Tells whether programmed activations are defined absolutely (from the origin of simulation times, i.e.
void	absoluteProgrammedActivationsWanted (bool on) throw ()
	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 throw ( SchedulingException )
	Returns a reference to the internal list of programmed activations of this object.
virtual void	setProgrammedActivations (const SimulationTickList &newActivationsList) throw ()
	Sets the list of programmed activations for this object to specified value.
virtual void	addProgrammedActivations (const SimulationTickList &additionalActivationsList) throw ()
	Adds the specified list of simulation ticks to the list of activation ticks for this object.
virtual void	setUniqueProgrammedTicks () throw ()
	Ensures that the programmed ticks for this object are unique, which means that, after this method call, this object will not be scheduled multiple times for any given simulation tick.
virtual Events::SimulationTick	getBirthTime () const throw ()
	Returns the birth time, expressed in simulation ticks, of this active object.
virtual void	setBirthTime (Events::SimulationTick birthSimulationTick) throw ()
	Sets the birth time, expressed in simulation ticks, of this active object.
virtual void	onActivation (Events::SimulationTick newTick)=0 throw ()
	Pure virtual method, which is called when this active object gets activated on behalf of the scheduler.
virtual void	onSkip (Events::SimulationTick skippedStep) throw ( SchedulingException )
	Called whenever the scheduler had to skip a period of activation for this object.
virtual void	onImpossibleActivation (Events::SimulationTick missedStep) throw ( SchedulingException )
	Called whenever the scheduler was unable to activate this object.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
Protected Member Functions
Events::SimulationTick	getLocalTime () const throw ()
	Returns this object local time, as if the origin of time was this object creation.
Protected Attributes
ObjectSchedulingPolicy	_policy
	Determines the scheduling policy of this object.
Weight	_weight
	Describe the average processing need for each activation of this object.
Events::Period	_period
	Tells what is the requested scheduling period for this object.
SimulationTickList *	_programmedTriggerTicks
	Records the list of programmed simulation ticks that will be used by the scheduler to activate this object.
bool	_absoluteTriggers
	Tells whether the programmed trigger ticks should be understood as absolute (i.e.
Events::SimulationTick	_birthTime
	The date of birth of this object, expressed in simulation time.

Member Typedef Documentation

typedef std::list<Events::SimulationTick> OSDL::Engine::ActiveObject::SimulationTickList

Types for lists of simulation ticks.

Definition at line 88 of file OSDLActiveObject.h.

Constructor & Destructor Documentation

ActiveObject::ActiveObject	(	Events::Period	period = `1`,
		ObjectSchedulingPolicy	policy = `relaxed`,
		Weight	weight = `1`
	)			throw () `[explicit]`

Constructor of a periodically activated object.

Parameters:

	period	tells how many simulation steps are to be waited by the scheduler until the active object is activated again. The period must not be null.
	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.

Note:: Do not mix up this constructor with the one for programmed objects, since their arguments are almost the same.

Definition at line 21 of file OSDLActiveObject.cc.

ActiveObject::ActiveObject	(	const SimulationTickList &	triggeringStates,
		bool	absolutlyDefined = `true`,
		ObjectSchedulingPolicy	policy = `relaxed`,
		Weight	weight = `1`
	)			throw () `[explicit]`

Constructor of a object activated only on specifically programmed simulation steps.

Parameters:

	triggeringStates	is the list of simulation ticks where the activation should occur. The object does not take ownership of this list, it will make a copy of it.
	absolutlyDefined	tells if the specified steps are defined absolutly, or relatively to the current simulation step.
	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.

Note:: Do not mix up this constructor with the one for periodic objects, since their arguments are almost the same.

Definition at line 34 of file OSDLActiveObject.cc.

ActiveObject::ActiveObject	(	Events::SimulationTick	triggerTick,
		bool	absolutlyDefined,
		ObjectSchedulingPolicy	policy = `relaxed`,
		Weight	weight = `1`
	)			throw () `[explicit]`

Constructor of a object activated only on a specific simulation step.

Parameters:

	triggerTick	is the simulation step when this object will be activated.
	absolutlyDefined	tells if the specified steps are defined absolutly, or relatively to the current simulation step. No default value can be given for that parameter, since there would be an ambiguity with first constructor on any call with only one argument.
	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.

Note:: Do not mix up this constructor with the one for programmed objects, since their arguments are almost the same.

Definition at line 48 of file OSDLActiveObject.cc.

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

Virtual destructor, which performs automatic unsubscribing of this object from the scheduler.

Definition at line 63 of file OSDLActiveObject.cc.

References _programmedTriggerTicks.

Member Function Documentation

ObjectSchedulingPolicy ActiveObject::getPolicy ( ) const throw () [virtual]

Returns the scheduling policy for this active object.

Definition at line 70 of file OSDLActiveObject.cc.

References _policy.

Weight ActiveObject::getWeight ( ) const throw () [virtual]

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 76 of file OSDLActiveObject.cc.

References _weight.

Period ActiveObject::getPeriod ( ) const throw () [virtual]

Returns the period for this active object.

Note:: A null (0) value denotes a pure programmed active object.

Definition at line 82 of file OSDLActiveObject.cc.

References _period.

void ActiveObject::setPeriod ( Events::Period newPeriod ) throw () [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.

Note:: An object will be considered as a periodically-activated one iff its period is non-zero. Zero means not activated on a regular basis thanks to periodic slots.

Definition at line 88 of file OSDLActiveObject.cc.

Hertz ActiveObject::setFrequency ( Events::Hertz newFrequency ) throw ( SchedulingException ) [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.

Definition at line 94 of file OSDLActiveObject.cc.

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

bool ActiveObject::hasProgrammedActivations ( ) const throw () [virtual]

Tells whether this object has programmed activations set.

Definition at line 134 of file OSDLActiveObject.cc.

References _programmedTriggerTicks.

bool ActiveObject::areProgrammedActivationsAbsolute ( ) const throw ()

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 141 of file OSDLActiveObject.cc.

References _absoluteTriggers.

void ActiveObject::absoluteProgrammedActivationsWanted ( bool on ) throw ()

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.

Definition at line 147 of file OSDLActiveObject.cc.

const ActiveObject::SimulationTickList & ActiveObject::getProgrammedActivations ( ) const throw ( SchedulingException ) [virtual]

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

Exceptions:

SchedulingException

if the object had no programmed activations.

See also:: hasProgrammedActivations to check for programmed activations before.

Definition at line 154 of file OSDLActiveObject.cc.

References _programmedTriggerTicks.

void ActiveObject::setProgrammedActivations ( const SimulationTickList & newActivationsList ) throw () [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.

See also:: addProgrammedActivations

Definition at line 167 of file OSDLActiveObject.cc.

void ActiveObject::addProgrammedActivations ( const SimulationTickList & additionalActivationsList ) throw () [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 which will activate the object too.

Note:: The method will not ensure that each tick is present at most one time in the object activation list : one object can by programmed multiple times in a single simulation tick.

Definition at line 179 of file OSDLActiveObject.cc.

void ActiveObject::setUniqueProgrammedTicks ( ) throw () [virtual]

Ensures that the programmed ticks for this object are unique, which means that, after this method call, this object will not be scheduled multiple times for any given simulation tick.

Note:: One can wish an object is scheduled multiple times for a given simulation tick, so having unique elements in programmed lists is an option.

Definition at line 197 of file OSDLActiveObject.cc.

References _programmedTriggerTicks.

SimulationTick ActiveObject::getBirthTime ( ) const throw () [virtual]

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

Definition at line 204 of file OSDLActiveObject.cc.

References _birthTime.

void ActiveObject::setBirthTime ( Events::SimulationTick birthSimulationTick ) throw () [virtual]

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

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

Definition at line 210 of file OSDLActiveObject.cc.

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

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 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

void ActiveObject::onSkip ( Events::SimulationTick skippedStep ) throw ( SchedulingException ) [virtual]

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:

skippedStep

tells which step was skipped.

Exceptions:

SchedulingException

if this active object cannot stand skipped stimulation steps.

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

Definition at line 216 of file OSDLActiveObject.cc.

References OSDL::Video::Pixels::toString().

void ActiveObject::onImpossibleActivation ( Events::SimulationTick missedStep ) throw ( SchedulingException ) [virtual]

Called whenever the scheduler was unable to activate this object.

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

Default behaviour for this method is : throw a SchedulingException.

Parameters:

missedStep

tells which step is out of range.

Exceptions:

SchedulingException

if this active object should not stand activation failures.

Definition at line 228 of file OSDLActiveObject.cc.

References OSDL::Video::Pixels::toString().

const string ActiveObject::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const throw () [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 in OSDL::MVC::Model.

Definition at line 239 of file OSDLActiveObject.cc.

References OSDL::Video::Pixels::toString().

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

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

Member Data Documentation

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

Determines the scheduling policy of this object.

Definition at line 468 of file OSDLActiveObject.h.

Referenced by getPolicy().

Weight OSDL::Engine::ActiveObject::_weight [protected]

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

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

Definition at line 478 of file OSDLActiveObject.h.

Referenced by getWeight().

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

Tells what is the requested scheduling period for this object.

Note:: A null (0) value denotes a programmed active object.

Definition at line 488 of file OSDLActiveObject.h.

Referenced by getPeriod().

SimulationTickList* OSDL::Engine::ActiveObject::_programmedTriggerTicks [protected]

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

Note:: No particular order is to be enforced.

Definition at line 498 of file OSDLActiveObject.h.

Referenced by getProgrammedActivations(), hasProgrammedActivations(), setUniqueProgrammedTicks(), and ~ActiveObject().

bool OSDL::Engine::ActiveObject::_absoluteTriggers [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 the moment the object is registered).

Is true by default.

Definition at line 510 of file OSDLActiveObject.h.

Referenced by areProgrammedActivationsAbsolute().

Events::SimulationTick OSDL::Engine::ActiveObject::_birthTime [protected]

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

Note:: the date of birth is neither the creation time of this active object (since it could be created even before the scheduler exists), nor the time where this object is scheduled for the first time, but the time it was registered to the scheduler.

Definition at line 524 of file OSDLActiveObject.h.

Referenced by getBirthTime().

OSDL::Engine::ActiveObject Class Reference

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation