OSDL::Engine::ActiveObject Class Reference

Active objects are dynamic objects, i.e. More...

#include <OSDLActiveObject.h>

Inheritance diagram for OSDL::Engine::ActiveObject:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 ActiveObject (ObjectSchedulingPolicy policy=relaxed, Weight weight=1)
 Constructor of an active object.
virtual ~ActiveObject () throw ()
 Virtual destructor.
virtual void registerToScheduler ()=0
 Registers this active object to the supposedly already existing scheduler.
virtual void unregisterFromScheduler ()=0
 Unregisters this active object from the existing scheduler to whom it was supposedly registered.
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.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns an user-friendly description of the state of 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

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

Active objects are dynamic objects, i.e.

objects which need some CPU time, since they "live", i.e. have a spontaneous behaviour.

Once registered, 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.

The ActiveObject class is abstract, it has two main child classes, one for objects whose activation must be periodic (PeriodicalActiveObject) and one for objects that rely on specifically programmed activation ticks (ProgrammedActiveObject).

An active object can be implemented according to one of two classic approaches regarding time and state management.

Indeed, 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 fully corrected in time (n+1), whereas the second approach demands all simulation ticks to be processed and therefore would not allow the scheduler, if in the hurry, to skip any tick. However, not all behaviours can respect 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 trajectory of its wings would depend only on the simulation time, and therefore would not be affected by past scheduling skips. The wheel angle would be computed only from its initial time and position, just adding to the initial angle the angular speed times the simulation time elapsed since the birth of this active object, i.e. the computing for simulation time n depends only of n and not on the computings made the previous ticks.

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. If a simulation tick had to be skipped then the windmill would turn slower than requested.

Unfortunately not all behaviours can follow the first approach.

For the corresponding 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.

Note:
Active objects have to be explicitly registered to the scheduler, so that their actual birth can happen at any time after their creation: active objects will start to live as soon as they are registered to the scheduler and that scheduler runs (these two events can happen in any order).
When the scheduler is running, the only way of deleting a scheduled object is to have it removed by another object, as they are the only code to be executed (and input or rendering tasks are not expected to remove active objects).

Definition at line 115 of file OSDLActiveObject.h.


Constructor & Destructor Documentation

ActiveObject::ActiveObject ( ObjectSchedulingPolicy  policy = relaxed,
Weight  weight = 1 
) [explicit]

Constructor of an active object.

Parameters:
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.

Definition at line 50 of file OSDLActiveObject.cc.

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

Virtual destructor.

Note:
The object is expected to be already unsubscribed from the scheduler (probably by the destructor of its actual child class), otherwise an error is logged.

Definition at line 62 of file OSDLActiveObject.cc.

References _registered, and toString().


Member Function Documentation

SimulationTick ActiveObject::getBirthTick (  )  const [virtual]

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

Definition at line 107 of file OSDLActiveObject.cc.

References _birthTick.

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

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

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

ObjectSchedulingPolicy ActiveObject::getPolicy (  )  const [virtual]

Returns the scheduling policy for this active object.

Definition at line 80 of file OSDLActiveObject.cc.

References _policy.

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

Weight ActiveObject::getWeight (  )  const [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 89 of file OSDLActiveObject.cc.

References _weight.

virtual void OSDL::Engine::ActiveObject::onActivation ( Events::SimulationTick  newTick  )  [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 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]

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.
virtual void OSDL::Engine::ActiveObject::onSkip ( Events::SimulationTick  skippedTick  )  [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:
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.
virtual void OSDL::Engine::ActiveObject::registerToScheduler (  )  [pure virtual]

Registers this active object to the supposedly already existing scheduler.

Exceptions:
SchedulingException if the operation failed.

Implemented in OSDL::Engine::PeriodicalActiveObject, and OSDL::Engine::ProgrammedActiveObject.

virtual void OSDL::Engine::ActiveObject::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.
Exceptions:
SchedulingException if the operation failed.

Reimplemented in OSDL::Engine::PeriodicalActiveObject.

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

const string ActiveObject::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 in OSDL::MVC::PeriodicalModel, OSDL::MVC::ProgrammedModel, OSDL::Engine::PeriodicalActiveObject, and OSDL::Engine::ProgrammedActiveObject.

Definition at line 138 of file OSDLActiveObject.cc.

References _birthTick, _policy, _registered, _weight, OSDL::Engine::relaxed, and OSDL::Engine::strict.

Referenced by ~ActiveObject().

virtual void OSDL::Engine::ActiveObject::unregisterFromScheduler (  )  [pure virtual]

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

Exceptions:
SchedulingException if the operation failed.

Implemented in OSDL::Engine::PeriodicalActiveObject, and OSDL::Engine::ProgrammedActiveObject.


Member Data Documentation

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

Determines the scheduling policy of this object.

Definition at line 338 of file OSDLActiveObject.h.

Referenced by getPolicy(), and toString().

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

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

Definition at line 349 of file OSDLActiveObject.h.

Referenced by getWeight(), and toString().


The documentation for this class was generated from the following files:
Generated on Mon Nov 29 14:05:32 2010 for OSDL by  doxygen 1.6.3