OSDL::Engine::Scheduler Class Reference

This scheduler manages active objects so that they are in turn granted with the processing power they requested. More...

#include <OSDLScheduler.h>

Collaboration diagram for OSDL::Engine::Scheduler:
Collaboration graph
[legend]

List of all members.

Public Member Functions

virtual bool hasRenderer () const
 Tells whether a renderer is available to this scheduler.
virtual Rendering::Renderer & getRenderer () const
 Returns currently used renderer, if any.
virtual void setRenderer (Rendering::Renderer &newRenderer)
 Assigns a new renderer, which will be called on every rendering tick, either to actually render, or to be notified of a rendering skip.
virtual void setScreenshotMode (bool on, const std::string &frameFilenamePrefix, Ceylan::Maths::Hertz frameFrequency=25)
 Tells whether the application should run interactively, in real time (if on is false), or if it should run in snapshot mode, with a virtual fixed framerate (as specified as frameFrequency), with logic and rendering taking all the time they need.
virtual void setTimeSliceDuration (Ceylan::System::Microsecond engineTickDuration)
 Defines how many microseconds an engine tick should last, and updates accordingly the simulation and rendering ticks.
virtual Ceylan::System::Microsecond getTimeSliceDuration () const
 Returns the current time slice duration, as used by this scheduler.
virtual void setSimulationFrequency (Ceylan::Maths::Hertz frequency)
 Sets the simulation frequency, by evaluating the number of engine ticks to be associated to one simulation tick for frequency to be met.
virtual Events::Period getSimulationTickCount () const
 Returns the number of engine ticks which correspond to one simulation tick.
virtual void setRenderingFrequency (Ceylan::Maths::Hertz frequency)
 Sets the rendering frequency, by evaluating the number of engine ticks to be associated to one rendering tick.
virtual Events::Period getRenderingTickCount () const
 Returns the number of engine ticks which correspond to one rendering tick.
virtual void setScreenshotFrequency (Ceylan::Maths::Hertz frequency)
 Sets the screenshot frequency, by evaluating the number of engine ticks to be associated to one screenshot tick for frequency to be met.
virtual Events::Period getScreenshotTickCount () const
 Returns the number of engine ticks which correspond to one screenshot tick.
virtual void setInputPollingFrequency (Ceylan::Maths::Hertz frequency)
 Sets the input polling frequency, by evaluating the number of engine ticks to be associated to one input tick.
virtual Events::Period getInputPollingTickCount () const
 Returns the number of engine ticks which correspond to one input tick.
virtual void setIdleCallback (Ceylan::System::Callback idleCallback=0, void *callbackData=0, Ceylan::System::Microsecond callbackExpectedMaxDuration=0)
 Sets the idle function, which is called whenever the scheduler detects a period of idle activity.
virtual Events::EngineTick getCurrentEngineTick () const
 Returns the current actual engine tick.
virtual Events::SimulationTick getCurrentSimulationTick () const
 Returns the current actual simulation tick.
virtual Events::RenderingTick getCurrentRenderingTick () const
 Returns the current actual rendering tick.
virtual Events::InputTick getCurrentInputTick () const
 Returns the current actual input tick.
virtual Events::SimulationTick getNumberOfSimulationTicksFor (Ceylan::System::Millisecond duration) const
virtual Events::RenderingTick getNumberOfRenderingTicksFor (Ceylan::System::Millisecond duration) const
virtual Events::InputTick getNumberOfInputTicksFor (Ceylan::System::Millisecond duration) const
virtual void registerPeriodicalObject (PeriodicalActiveObject &toRegister)
 Registers specified periodical active object in scheduling slots.
virtual void unregisterPeriodicalObject (PeriodicalActiveObject &toUnregister)
 Unregisters specified periodical active object.
virtual void registerProgrammedObject (ProgrammedActiveObject &toRegister)
 Registers specified periodical active object in scheduling slots.
virtual void unregisterProgrammedObject (ProgrammedActiveObject &toUnregister)
 Unregisters specified active object.
virtual void schedule ()
 Launches the schedule loop, which behaves as a specialized never-ending event loop.
virtual void stop ()
 Requests the scheduler to stop its activities at the end of current engine tick.
virtual void setStopCallback (Ceylan::System::Callback stopCallback=0, void *callbackData=0)
 Registers a new stop callback, which will be called each time the scheduler stops.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns an user-friendly description of the state of this object.

Static Public Member Functions

static Scheduler & GetExistingScheduler ()
 Returns the one and only one scheduler instance, that should be already available.
static Scheduler & GetScheduler ()
 Returns the one and only scheduler instance.
static void DeleteExistingScheduler ()
 Deletes the existing shared scheduler.
static void DeleteScheduler ()
 Deletes the shared scheduler, if any.
static void StopExistingScheduler ()
 Deletes the shared scheduler, if any.

Static Public Attributes

static const
Ceylan::System::Microsecond 		DefaultEngineTickDuration = 1000
 Determines the default engine tick duration.
static const Ceylan::Maths::Hertz DefaultSimulationFrequency = 100
 Determines the default frequency for logic (simulation).
static const Ceylan::Maths::Hertz DefaultRenderingFrequency = 40
 Determines the default frequency for rendering.
static const Ceylan::Uint32 DefaultMovieFrameFrequency = 25
 By default, generated screenshots will be saved on the purpose of being gathered by a movie with 25 images per second.
static const Ceylan::Maths::Hertz DefaultInputFrequency = 20
 Determines the default frequency for input reading.

Protected Member Functions

 Scheduler ()
 Constructs a new scheduler.
virtual ~Scheduler () throw ()
 Virtual destructor, any existing renderer is deleted whereas no active object is destroyed.
virtual void scheduleBestEffort ()
 Actual scheduling method used for real-time and/or interactive applications.
virtual void scheduleNoDeadline (bool pollInputs=true)
 Actual scheduling method used for batch applications, which do not care about keeping any user-defined pace.
virtual Events::EngineTick computeEngineTickFromCurrentTime ()
 Returns the value that should be the engine tick, if no scheduling skip had happened.
virtual void scheduleSimulation (Events::SimulationTick current)
 Takes care of the simulation by making live relevant active objects, when a simulation tick is reached.
virtual void scheduleProgrammedObjects (Events::SimulationTick current)
 Takes care of the simulation of programmed objects, by activating the relevant ones.
virtual void schedulePeriodicObjects (Events::SimulationTick currentSimulationTick)
 Takes care of the simulation of periodic objects, by activating the relevant ones.
virtual void scheduleRendering (Events::RenderingTick currentRenderingTick)
 Triggers the rendering.
virtual void scheduleInput (Events::InputTick currentInputTick)
 Triggers the input update.
virtual void scheduleProgrammedObjectList (Events::RenderingTick currentSimulationTick, ListOfProgrammedActiveObjects &objectList)
 Helper method to schedule (execute) in turn every programmed active object of the specified list.
virtual void onSimulationSkipped (Events::SimulationTick skipped)
 Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified simulation tick, which will have therefore to be skipped.
virtual void onRenderingSkipped (Events::RenderingTick skipped)
 Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified rendering tick, which will have therefore to be skipped.
virtual void onInputSkipped (Events::InputTick skipped)
 Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified input tick, which will have therefore to be skipped.
virtual void onIdle ()
 Called whenever the application is deemed idle.
virtual void onScheduleFailure (Delay currentBucket)
 Called whenever the scheduler does not succeed in keeping up the pace with what the application demanded: if the runtime resources are not high enough, then the scheduler may fail regularly and progressively fill up its delay bucket.
virtual void programTriggerFor (ProgrammedActiveObject &objectToProgram, Events::SimulationTick targetTick)
 Adds a programmed activation for objectToProgram at simulation tick targetTick.
virtual PeriodicSlot & getPeriodicSlotFor (Events::Period period)
 Returns the supposedly already existing internal periodic slot for the specified period.
virtual PeriodicSlot & returnPeriodicSlotFor (Events::Period period)
 Returns the internal periodic slot corresponding to specified period.
virtual void setInitialBirthTicks (Events::SimulationTick birthSimulationTick)
std::string describeProgrammedTicks () const
 Returns a textual description of the ticks that are currently programmed.

Protected Attributes

bool _screenshotMode
 Tells whether screenshot mode is activated (default: deactivated).
std::string _frameFilenamePrefix
 Records which prefix should be used to name numbered screenshot files.
Ceylan::Maths::Hertz _desiredScreenshotFrequency
 Records the user-defined screenshot frequency, which is the targeted number of frames per second.
Events::Period _screenshotPeriod
 Stores the period corresponding to the planned framerate for the movie that would be generated, if screenshot mode is activated.
std::list< PeriodicSlot * > _periodicSlots
 A list containing all available periodic slots, ordered by increasing periods.
std::list< ActiveObject * > _initialRegisteredObjects
 A list containing all the active objects (either periodical or programmed) that were registered before the scheduler is started.
std::map
< Events::SimulationTick,
ListOfProgrammedActiveObjects > 		_programmedActivated
 Map for programmed activations.
Ceylan::System::Microsecond _engineTickDuration
 Defines the duration in microseconds of an elementary scheduler tick.
Ceylan::Uint32 _secondToEngineTick
 Multiplicative factor that allows to convert seconds into engine ticks.
Events::EngineTick _currentEngineTick
 Records the current engine tick.
Events::SimulationTick _currentSimulationTick
 Records the current simulation tick.
Events::RenderingTick _currentRenderingTick
 Records the current rendering tick.
Events::RenderingTick _currentInputTick
 Records the current input tick.
Events::Period _simulationPeriod
 Duration between two successive simulation ticks, expressed in engine ticks.
Events::Period _renderingPeriod
 Duration between two successive rendering ticks, expressed in engine ticks.
Events::Period _inputPeriod
 Duration between two successive input ticks, expressed in engine ticks.
Ceylan::Maths::Hertz _desiredSimulationFrequency
 Records the user-defined simulation frequency.
Ceylan::Maths::Hertz _desiredRenderingFrequency
 Records the user-defined rendering frequency.
Ceylan::Maths::Hertz _desiredInputFrequency
 Records the user-defined input frequency.
Ceylan::System::Callback _idleCallback
 The idle callback, if any, to be called by the scheduler.
void * _idleCallbackData
 The data, if any, to provide to the idle callback.
Ceylan::System::Microsecond _idleCallbackMaxDuration
 An estimated upper bound of the duration of current idle callback.
Ceylan::System::Microsecond _idleCallbackMinMeasuredDuration
 The smallest measured actual duration for past idle callbacks.
Ceylan::System::Microsecond _idleCallbackMaxMeasuredDuration
 The highest measured actual duration for past idle callbacks.
Ceylan::Uint32 _idleCallsCount
 Count the number of idle calls made during the current scheduler session.
bool _isRunning
 Tells whether the scheduler is running.
bool _stopRequested
 Tells whether the scheduler has been requested to stop.
Ceylan::System::Callback _stopCallback
 The stop callback, if any, to be called by the scheduler.
void * _stopCallbackData
 The data, if any, to provide to the stop callback.
Ceylan::System::Second _scheduleStartingSecond
 Stores the second when scheduling started.
Ceylan::System::Microsecond _scheduleStartingMicrosecond
 Stores the microsecond when scheduling started.
Ceylan::Uint32 _recoveredSimulationTicks
 Records how many simulation ticks were recovered since the scheduler was started.
Ceylan::Uint32 _missedSimulationTicks
 Records how many simulation ticks were missed since the scheduler was started.
Ceylan::Uint32 _recoveredRenderingTicks
 Records how many rendering ticks were recovered since the scheduler was started.
Ceylan::Uint32 _missedRenderingTicks
 Records how many rendering ticks were missed since the scheduler was started.
Ceylan::Uint32 _recoveredInputPollingTicks
 Records how many input ticks were recovered since the scheduler was started.
Ceylan::Uint32 _missedInputPollingTicks
 Records how many input ticks were missed since the scheduler was started.
Ceylan::Uint32 _scheduleFailureCount
 Records how many schedule failures were reported.
Events::EventsModule * _eventsModule
 References the events module, if necessary.
Rendering::Renderer * _renderer
 References the renderer to be used, if any.
Video::VideoModule * _videoModule
 References the video module, if necessary.
bool _subSecondSleepsAvailable
 Tells whether sub-second sleeps can be used, to avoid monopolizing the CPU.

Static Protected Attributes

static const Delay ShutdownBucketLevel = 1000000
 Threshold for the level of delay bucket, above which the scheduler will be stopped automatically.

Private Member Functions

 Scheduler (const Scheduler &source)
 Copy constructor made private to ensure that it will never be called.
Scheduler & operator= (const Scheduler &source)
 Assignment operator made private to ensure that it will never be called.

Static Private Attributes

static Scheduler * _internalScheduler = 0
 The internal single instance of scheduler, if any.

Detailed Description

This scheduler manages active objects so that they are in turn granted with the processing power they requested.

Two kinds of active objects can be scheduled:

These ticks are defined relatively to the moment when they have been declared to the scheduler, or as absolute ticks.

Note:
For the application objects, the only relevant and useful unit for time with respect to scheduling is the simulation time, expressed in Events::SimulationTick. They should base their behaviour on this time, and only this time (i.e. they should not use directly the user time).

The rendering task is scheduled thanks to Events::RenderingTick, which allows to specify any frequency independently from logic frequency.

Whereas the scheduler internal time (EngineTick) is kept in synchronism with actual user time (in quasi-hard real time), the simulation and rendering times cannot ensure that deadlines are respected (because of many reasons, from the machine load to peak resource needs, OS scheduling and so on). Therefore they are only in soft real-time, and it is the job of the scheduler to ensure that everything is done on time, on a best effort basis. Whenever a failure to meet a deadline occurs, the impacted objects are provided with a means of being noticed, in order to be able to take any counter-measures they can.

The scheduler has two main data structures:

Our scheduler can follow two different behaviours:

Choosing a high logic frequency, and moreover higher than the rendering frequency, is the way to go, since it allows to get rid of interpolation and resampling issues. Clearly 33 Hz is the very least logic frequency one should use, and 100 Hz or higher frequencies should be preferred. Ideally logic frequency should be multiple times higher than rendering frequency.

For the logic, the only time unit that should be used is the simulation tick. Do not try to depend on any real time measurement, since it would bypass the efforts of the scheduler to provide the application with a virtual fixed-rate logic time, and make it fail.

For the rendering, beware that some graphic primitives wait for vsync, which may freeze the process until the remaining part of the, say, 1/60th of second is reached. This hard real time practise would interfere badly with any scheduler. You can disable vsync, but one might experience more tearing and shearing. Conversely, the scheduler could take this behaviour into account and synchronize itself on the display refresh rate. It would have to manage a decrease in the frame rate if the scene complexity comes too close to have a rendering duration of the magic times (1/60 of second, 1/30 etc.): because of random variations, some frames would go slightly over or under the duration, leading to an irregular framerate which may be visually disturbing. Better switch to lower rendering rates and have a constant frame rate. Or, still better, use double-buffering and non-blocking operations.

Rendering is obtained thanks to a renderer, if available, which is called at each rendering tick. If no renderer is being used, then the video module will be used, and requested to redraw at each rendering tick. The scheduled objects are in this case responsible for the updating of the screen surface.

add a means of knowing whether hardware synch with refresh rate is possible and, if so, use it not to schedule instead of the scheduler, but to make the scheduler start at the right time, so that it keeps naturally the synchronisation with the refresh rate. Or force the engine tick to be a hardware-locked frame pace.

Apart the logic and rendering frequencies, the scheduler has to handle the input frequency, which is the frequency at which input devices (such as keyboard, mouse, joysticks, etc.) are updated, according to pending low level events. One of the purposes of input handling is to have the controllers updated so that the simulation world is interactive. The input loop provided by the SDL back-end runs at 100 Hz, so higher frequencies would be useless.

Note:
With default settings, simulation frequency granularity should be less than + or -3 Hz on average.
The Scheduler is meant to be used as a singleton: having multiple scheduler instances in use would be meaningless, and they would probably fail collectively.

The scheduler has been designed so that no multithread paradigm is needed, but it could be useful one day to parallelize (if possible) at least the simulation evaluation, since there may be numerous active objects that could take advantage of hyperthreading, dual cores, etc.

For the simulation tick, there could be too a two-pass algorithm: first compute, but do not apply, all the newer states of all objects, then, second pass, apply them. The problem is indeed that an object whose state depends on the state of other objects should take them into account at time t, when computing state at t+1, in their state at t, and not t+1. If all objects were to be updated in a single row, the first ones would be already at t+1 while the remaining ones would have to be updated from t to t+1. As among the remaining objects some may depend on the first ones, they would take into account t+1 states and not t states. Moreover, as there may be cyclic dependencies (say, for collisions, where two objects became mutually dependent), no right order can be found. Therefore a two-pass algorithm may be helpful, but such an accuracy for client-side processings would be most probably overkill. As for server-side management, more complex and robust approaches could be used, as the Orge server.

Note:
Some breathing time (letting the operating system schedule other processes) would be probably necessary, since for example the Linux kernel seems to take control away for a rather long while when it detects a program running at 100%. However it would involve waiting regularly for 1ms (kernel 2.6) or 10ms (kernel 2.4), and many skips would occur. The user can choose which behaviour to retain by selecting the kind of idle calls that should be performed.
The scheduler can run continuously for up to 48 days: after, engine ticks will overflow and it will lead to a scheduler shutdown.

Definition at line 265 of file OSDLScheduler.h.

Constructor & Destructor Documentation

Scheduler::Scheduler (  )  [explicit, protected]

Constructs a new scheduler.

Note:
Protected to ensure the singleton pattern is respected.
Exceptions:
SchedulingException if the scheduler could not be returned, for example if no subsecond sleep is available on this platform.

Definition at line 1264 of file OSDLScheduler.cc.

References _subSecondSleepsAvailable, DefaultEngineTickDuration, setTimeSliceDuration(), and OSDL::Video::Pixels::toString().

Referenced by GetScheduler().

Scheduler::~Scheduler (  )  throw () [protected, virtual]

Virtual destructor, any existing renderer is deleted whereas no active object is destroyed.

Note:
Protected to ensure the singleton pattern is respected.

Definition at line 1330 of file OSDLScheduler.cc.

References _periodicSlots, and _renderer.

OSDL::Engine::Scheduler::Scheduler ( const Scheduler &  source  )  [explicit, private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

EngineTick Scheduler::computeEngineTickFromCurrentTime (  )  [protected, virtual]

Returns the value that should be the engine tick, if no scheduling skip had happened.

This engine tick is computed from the current time since the beginning of scheduling, which is obtained thanks to a call to a precise actual time measurement minus the offset corresponding to the starting time of the scheduling.

See also:
Ceylan::getPreciseTime, _scheduleStartingSecond, _scheduleStartingMicrosecond

Definition at line 3478 of file OSDLScheduler.cc.

References _engineTickDuration, _scheduleStartingMicrosecond, _scheduleStartingSecond, _secondToEngineTick, and _stopRequested.

Referenced by scheduleBestEffort().

void Scheduler::DeleteExistingScheduler (  )  [static]

Deletes the existing shared scheduler.

Exceptions:
SchedulingException if not scheduler was available.

Definition at line 1189 of file OSDLScheduler.cc.

void Scheduler::DeleteScheduler (  )  [static]

Deletes the shared scheduler, if any.

Definition at line 1208 of file OSDLScheduler.cc.

std::string Scheduler::describeProgrammedTicks (  )  const [protected]

Returns a textual description of the ticks that are currently programmed.

Definition at line 3973 of file OSDLScheduler.cc.

References _programmedActivated, and toString().

EngineTick Scheduler::getCurrentEngineTick (  )  const [virtual]

Returns the current actual engine tick.

Definition at line 443 of file OSDLScheduler.cc.

References _currentEngineTick.

InputTick Scheduler::getCurrentInputTick (  )  const [virtual]

Returns the current actual input tick.

Definition at line 470 of file OSDLScheduler.cc.

References _currentInputTick.

RenderingTick Scheduler::getCurrentRenderingTick (  )  const [virtual]

Returns the current actual rendering tick.

Definition at line 461 of file OSDLScheduler.cc.

References _currentRenderingTick.

SimulationTick Scheduler::getCurrentSimulationTick (  )  const [virtual]

Returns the current actual simulation tick.

Definition at line 452 of file OSDLScheduler.cc.

References _currentSimulationTick.

Scheduler & Scheduler::GetExistingScheduler (  )  [static]

Returns the one and only one scheduler instance, that should be already available.

The returned value is a reference and not a pointer, to avoid any abnormal deallocation by its users, that should never deallocate the scheduler.

Exceptions:
SchedulingException if there is no scheduler available.

Definition at line 1146 of file OSDLScheduler.cc.

Referenced by OSDL::Engine::PeriodicalActiveObject::convertDurationToActivationCount(), OSDL::Engine::PeriodicalActiveObject::PeriodicalActiveObject(), OSDL::Engine::ProgrammedActiveObject::registerToScheduler(), OSDL::Engine::PeriodicalActiveObject::registerToScheduler(), OSDL::Engine::ProgrammedActiveObject::unregisterFromScheduler(), and OSDL::Engine::PeriodicalActiveObject::unregisterFromScheduler().

Period Scheduler::getInputPollingTickCount (  )  const [virtual]

Returns the number of engine ticks which correspond to one input tick.

Note:
It allows to take into account the round-off that had to be performed by the setInputPollingFrequency method.

Definition at line 434 of file OSDLScheduler.cc.

References _inputPeriod.

Events::InputTick Scheduler::getNumberOfInputTicksFor ( Ceylan::System::Millisecond  duration  )  const [virtual]

Definition at line 504 of file OSDLScheduler.cc.

References _engineTickDuration, and _inputPeriod.

Events::RenderingTick Scheduler::getNumberOfRenderingTicksFor ( Ceylan::System::Millisecond  duration  )  const [virtual]

Definition at line 492 of file OSDLScheduler.cc.

References _engineTickDuration, and _renderingPeriod.

Events::SimulationTick Scheduler::getNumberOfSimulationTicksFor ( Ceylan::System::Millisecond  duration  )  const [virtual]

Definition at line 480 of file OSDLScheduler.cc.

References _engineTickDuration, and _simulationPeriod.

PeriodicSlot & Scheduler::getPeriodicSlotFor ( Events::Period  period  )  [protected, virtual]

Returns the supposedly already existing internal periodic slot for the specified period.

Exceptions:
SchedulingException if no slot could be found for this period.

Definition at line 3894 of file OSDLScheduler.cc.

References _periodicSlots, and OSDL::Video::Pixels::toString().

Referenced by unregisterPeriodicalObject().

Renderer & Scheduler::getRenderer (  )  const [virtual]

Returns currently used renderer, if any.

Exceptions:
SchedulingException if no renderer is available.

Definition at line 161 of file OSDLScheduler.cc.

References _renderer.

Period Scheduler::getRenderingTickCount (  )  const [virtual]

Returns the number of engine ticks which correspond to one rendering tick.

Note:
It allows to take into account the round-off that had to be performed by the setRenderingFrequency method.

Definition at line 317 of file OSDLScheduler.cc.

References _renderingPeriod.

Scheduler & Scheduler::GetScheduler (  )  [static]

Returns the one and only scheduler instance.

If no scheduler was already available, a new singletoned instance is created.

The returned value is a reference and not a pointer, to avoid any abnormal deallocation by its users, that should never deallocate the scheduler.

Exceptions:
SchedulingException if the scheduler could not be returned.

Definition at line 1159 of file OSDLScheduler.cc.

References Scheduler(), and OSDL::Video::Pixels::toString().

Period Scheduler::getScreenshotTickCount (  )  const [virtual]

Returns the number of engine ticks which correspond to one screenshot tick.

Note:
It allows to take into account the round-off that had to be performed by the setScreenshotFrequency method.

Definition at line 368 of file OSDLScheduler.cc.

References _screenshotPeriod.

Period Scheduler::getSimulationTickCount (  )  const [virtual]

Returns the number of engine ticks which correspond to one simulation tick.

Note:
It allows to take into account the round-off that had to be performed by the setSimulationFrequency method.

Definition at line 269 of file OSDLScheduler.cc.

References _simulationPeriod.

Referenced by OSDL::Engine::PeriodicalActiveObject::convertDurationToActivationCount(), and OSDL::Engine::PeriodicalActiveObject::PeriodicalActiveObject().

Microsecond Scheduler::getTimeSliceDuration (  )  const [virtual]

Returns the current time slice duration, as used by this scheduler.

This is the duration of an engine tick.

Note:
Average settings would be 1000 microseconds = 1 millisecond for each engine tick.

Definition at line 222 of file OSDLScheduler.cc.

References _engineTickDuration.

Referenced by OSDL::Engine::PeriodicalActiveObject::convertDurationToActivationCount(), and OSDL::Engine::PeriodicalActiveObject::PeriodicalActiveObject().

bool Scheduler::hasRenderer (  )  const [virtual]

Tells whether a renderer is available to this scheduler.

If no renderer is registered, the video module will be used instead.

Definition at line 152 of file OSDLScheduler.cc.

References _renderer.

void Scheduler::onIdle (  )  [protected, virtual]

Called whenever the application is deemed idle.

Applies the idle behaviour, which can be user-defined (setIdleCallback), or otherwise which will default to micro-sleeps.

See also:
setIdleCallback.

Definition at line 3767 of file OSDLScheduler.cc.

References _idleCallback, _idleCallbackData, _idleCallsCount, _subSecondSleepsAvailable, and OSDL_SCHEDULE_LOG.

Referenced by scheduleBestEffort().

virtual void OSDL::Engine::Scheduler::onInputSkipped ( Events::InputTick  skipped  )  [protected, virtual]

Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified input tick, which will have therefore to be skipped.

By default, this method does nothing at all. As only the freshest inputs are generally useful, most applications will leave this method as a do-nothing one.

Note:
Skipping methods should be, on average, faster than their normally scheduled counterparts, otherwise the scheduler will have no chance of keeping up with the real time.

Referenced by scheduleBestEffort().

virtual void OSDL::Engine::Scheduler::onRenderingSkipped ( Events::RenderingTick  skipped  )  [protected, virtual]

Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified rendering tick, which will have therefore to be skipped.

By default, this method does nothing except complaining in the warning channel.

Note:
Skipping methods should be, on average, faster than their normally scheduled counterparts, otherwise the scheduler will have no chance of keeping up with the real time.

Referenced by scheduleBestEffort().

void Scheduler::onScheduleFailure ( Delay  currentBucket  )  [protected, virtual]

Called whenever the scheduler does not succeed in keeping up the pace with what the application demanded: if the runtime resources are not high enough, then the scheduler may fail regularly and progressively fill up its delay bucket.

In this case this method - made to be overloaded - is called with the current bucket value. It can then take countermeasures (preferably without taking too much time, otherwise it will be responsible for the scheduling failure).

The default implementation will send notifications in the error log channel if below ShutdownBucketLevel, and will stop the scheduler if higher.

See also:
ShutdownBucketLevel
Exceptions:
SchedulingException if the failure was deemed fatal.

Definition at line 3810 of file OSDLScheduler.cc.

References _currentEngineTick, _currentInputTick, _currentRenderingTick, _currentSimulationTick, _scheduleFailureCount, OSDL_SCHEDULE_LOG, ShutdownBucketLevel, stop(), OSDL::Video::Pixels::toString(), and toString().

Referenced by scheduleBestEffort().

virtual void OSDL::Engine::Scheduler::onSimulationSkipped ( Events::SimulationTick  skipped  )  [protected, virtual]

Overridable method called when this scheduler detects that processing power was not high enough to perform on time specified simulation tick, which will have therefore to be skipped.

By default, this method calls on all active objects whose simulation tick has been skipped their onSkip method.

Note:
If an object is registered multiple times for a given skipped simulation tick (ex: multiple periodic and/or programmed activations), then its onSkip method will be called as many times as it should have been activated.
Skipping methods should be, on average, faster than their normally scheduled counterparts (onNextTick), otherwise the scheduler will have no chance of keeping up with the real time.

Referenced by scheduleBestEffort().

Scheduler& OSDL::Engine::Scheduler::operator= ( const Scheduler &  source  )  [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

virtual void OSDL::Engine::Scheduler::programTriggerFor ( ProgrammedActiveObject &  objectToProgram,
Events::SimulationTick  targetTick 
) [protected, virtual]

Adds a programmed activation for objectToProgram at simulation tick targetTick.

Parameters:
objectToProgram the object whose activation is being programmed.
targetTick the simulation tick when specified object should be activated.

Referenced by registerProgrammedObject().

void Scheduler::registerPeriodicalObject ( PeriodicalActiveObject &  toRegister  )  [virtual]

Registers specified periodical active object in scheduling slots.

Parameters:
toRegister the periodical active object to register to the scheduler.

Definition at line 518 of file OSDLScheduler.cc.

References _currentSimulationTick, _initialRegisteredObjects, _isRunning, OSDL::Engine::PeriodicSlot::add(), OSDL::Engine::PeriodicalActiveObject::getPeriod(), OSDL::Engine::PeriodicalActiveObject::onRegistering(), returnPeriodicSlotFor(), and OSDL::Engine::PeriodicalActiveObject::setBirthTick().

Referenced by OSDL::Engine::PeriodicalActiveObject::registerToScheduler().

void Scheduler::registerProgrammedObject ( ProgrammedActiveObject &  toRegister  )  [virtual]

Registers specified periodical active object in scheduling slots.

Parameters:
toRegister the periodical active object to register to the scheduler.

Definition at line 588 of file OSDLScheduler.cc.

References _currentSimulationTick, _initialRegisteredObjects, _isRunning, OSDL::Engine::ProgrammedActiveObject::areProgrammedActivationsAbsolute(), OSDL::Engine::ProgrammedActiveObject::getProgrammedActivations(), OSDL::Engine::ProgrammedActiveObject::onRegistering(), programTriggerFor(), and OSDL::Engine::ActiveObject::setBirthTick().

Referenced by OSDL::Engine::ProgrammedActiveObject::registerToScheduler().

PeriodicSlot & Scheduler::returnPeriodicSlotFor ( Events::Period  period  )  [protected, virtual]

Returns the internal periodic slot corresponding to specified period.

If there is no slot for this period, a new slot is created and returned.

Definition at line 3918 of file OSDLScheduler.cc.

References _periodicSlots.

Referenced by registerPeriodicalObject().

void Scheduler::schedule (  )  [virtual]

Launches the schedule loop, which behaves as a specialized never-ending event loop.

Exceptions:
SchedulingException,when propagated from active objects having problems.

Definition at line 830 of file OSDLScheduler.cc.

References _eventsModule, _renderer, _screenshotMode, _videoModule, OSDL::CommonModule::getEventsModule(), OSDL::getExistingCommonModule(), OSDL::CommonModule::getVideoModule(), scheduleBestEffort(), scheduleNoDeadline(), and OSDL::Rendering::Renderer::toString().

void Scheduler::scheduleBestEffort (  )  [protected, virtual]

Actual scheduling method used for real-time and/or interactive applications.

Note:
Best efforts means that if deadlines cannot be met, some simulation or rendering ticks might be skipped.

Definition at line 1351 of file OSDLScheduler.cc.

References _currentEngineTick, _currentInputTick, _currentRenderingTick, _currentSimulationTick, _desiredInputFrequency, _desiredRenderingFrequency, _desiredSimulationFrequency, _engineTickDuration, _idleCallback, _idleCallbackMaxDuration, _idleCallbackMaxMeasuredDuration, _idleCallbackMinMeasuredDuration, _idleCallsCount, _inputPeriod, _isRunning, _missedInputPollingTicks, _missedRenderingTicks, _missedSimulationTicks, _recoveredInputPollingTicks, _recoveredRenderingTicks, _recoveredSimulationTicks, _renderingPeriod, _scheduleFailureCount, _scheduleStartingMicrosecond, _scheduleStartingSecond, _simulationPeriod, _stopCallback, _stopCallbackData, _stopRequested, computeEngineTickFromCurrentTime(), generate_master_palette::count, DefaultEngineTickDuration, onIdle(), onInputSkipped(), onRenderingSkipped(), onScheduleFailure(), onSimulationSkipped(), OSDL_SCHEDULE_LOG, scheduleInput(), scheduleRendering(), scheduleSimulation(), setInitialBirthTicks(), ShutdownBucketLevel, toString(), and OSDL::Video::Pixels::toString().

Referenced by schedule().

virtual void OSDL::Engine::Scheduler::scheduleInput ( Events::InputTick  currentInputTick  )  [protected, virtual]

Triggers the input update.

Parameters:
currentInputTick the current input tick.

Referenced by scheduleBestEffort(), and scheduleNoDeadline().

void Scheduler::scheduleNoDeadline ( bool  pollInputs = true  )  [protected, virtual]

Actual scheduling method used for batch applications, which do not care about keeping any user-defined pace.

Parameters:
pollInputs tells whether inputs should be polled nevertheless.
Note:
The program takes all the time it needs to perform its tasks, so that no simulation nor rendering tick is skipped, even if the whole processing takes significantly longer. Useful to generate screenshots.

Definition at line 3107 of file OSDLScheduler.cc.

References _currentEngineTick, _currentInputTick, _currentRenderingTick, _currentSimulationTick, _inputPeriod, _isRunning, _renderingPeriod, _scheduleStartingMicrosecond, _scheduleStartingSecond, _simulationPeriod, _stopCallback, _stopCallbackData, _stopRequested, _subSecondSleepsAvailable, OSDL_SCHEDULE_LOG, scheduleInput(), scheduleRendering(), scheduleSimulation(), setInitialBirthTicks(), toString(), and OSDL::Video::Pixels::toString().

Referenced by schedule().

virtual void OSDL::Engine::Scheduler::schedulePeriodicObjects ( Events::SimulationTick  currentSimulationTick  )  [protected, virtual]

Takes care of the simulation of periodic objects, by activating the relevant ones.

Parameters:
currentSimulationTick the simulation tick to perform, for objects to be able to behave appropriately, for example for first behaviour approach (stateless objects).
void Scheduler::scheduleProgrammedObjectList ( Events::RenderingTick  currentSimulationTick,
ListOfProgrammedActiveObjects &  objectList 
) [protected, virtual]

Helper method to schedule (execute) in turn every programmed active object of the specified list.

Parameters:
currentSimulationTick the simulation tick to be passed to the activated objects.
objectList the list of the programmed active objects to execute in turn.

Definition at line 3664 of file OSDLScheduler.cc.

virtual void OSDL::Engine::Scheduler::scheduleProgrammedObjects ( Events::SimulationTick  current  )  [protected, virtual]

Takes care of the simulation of programmed objects, by activating the relevant ones.

Parameters:
current the simulation tick to perform, for programmed objects to know to which programmed tick this activation corresponds.
virtual void OSDL::Engine::Scheduler::scheduleRendering ( Events::RenderingTick  currentRenderingTick  )  [protected, virtual]

Triggers the rendering.

Parameters:
currentRenderingTick the current rendering tick.

Referenced by scheduleBestEffort(), and scheduleNoDeadline().

virtual void OSDL::Engine::Scheduler::scheduleSimulation ( Events::SimulationTick  current  )  [protected, virtual]

Takes care of the simulation by making live relevant active objects, when a simulation tick is reached.

Parameters:
current the simulation tick to perform, for objects to be able to behave appropriatly, for example for first behaviour approach (stateless objects).

Referenced by scheduleBestEffort(), and scheduleNoDeadline().

void Scheduler::setIdleCallback ( Ceylan::System::Callback  idleCallback = 0,
void *  callbackData = 0,
Ceylan::System::Microsecond  callbackExpectedMaxDuration = 0 
) [virtual]

Sets the idle function, which is called whenever the scheduler detects a period of idle activity.

The callback can be useful for example to let the process yield some CPU time so that the OS does not consider it as too CPU-hungry, and does not take counter-measures against it.

Note:
Ensure that the maximum time spent in the idle callback is negligible compared to the period corresponding to the maximum engine frequency being set, so that it does not result in a too heavy load which would make the scheduler fail constantly because of its idle function.
Parameters:
idleCallback the idle callback, which can be set to null (0) to specify no idle callback is wanted.
callbackData the user-supplied data pointer that the idle callback will be given, if not null.
callbackExpectedMaxDuration the maximum duration, in microseconds, expected for this idle call-back. Helps the scheduler enforcing its target frequency. If this value is null, the idle callback will be launched once immediately (during the call of this method), and the measured duration, increased of 20%, will be kept as upper bound.

Any prior callback or callback data will be replaced by the one specified.

Definition at line 415 of file OSDLScheduler.cc.

References _idleCallback, _idleCallbackData, and _idleCallbackMaxDuration.

void Scheduler::setInitialBirthTicks ( Events::SimulationTick  birthSimulationTick  )  [protected, virtual]

Definition at line 3958 of file OSDLScheduler.cc.

References _initialRegisteredObjects.

Referenced by scheduleBestEffort(), and scheduleNoDeadline().

virtual void OSDL::Engine::Scheduler::setInputPollingFrequency ( Ceylan::Maths::Hertz  frequency  )  [virtual]

Sets the input polling frequency, by evaluating the number of engine ticks to be associated to one input tick.

Exceptions:
SchedulingException if requested frequency is superior to engine frequency.
Parameters:
frequency the new input polling frequency.
See also:
DefaultInputFrequency
void Scheduler::setRenderer ( Rendering::Renderer &  newRenderer  )  [virtual]

Assigns a new renderer, which will be called on every rendering tick, either to actually render, or to be notified of a rendering skip.

Parameters:
newRenderer the renderer to be used from now.
Note:
Will delete any previously existing renderer, and will take ownership of the specified renderer.

Definition at line 174 of file OSDLScheduler.cc.

References _renderer.

virtual void OSDL::Engine::Scheduler::setRenderingFrequency ( Ceylan::Maths::Hertz  frequency  )  [virtual]

Sets the rendering frequency, by evaluating the number of engine ticks to be associated to one rendering tick.

Parameters:
frequency the new rendering frequency.
Exceptions:
SchedulingException if requested frequency is superior to engine frequency.
See also:
DefaultRenderingFrequency
virtual void OSDL::Engine::Scheduler::setScreenshotFrequency ( Ceylan::Maths::Hertz  frequency  )  [virtual]

Sets the screenshot frequency, by evaluating the number of engine ticks to be associated to one screenshot tick for frequency to be met.

Parameters:
frequency the new screenshot frequency.
Exceptions:
SchedulingException if requested frequency is superior to engine frequency.
See also:
DefaultMovieFrameFrequency
virtual void OSDL::Engine::Scheduler::setScreenshotMode ( bool  on,
const std::string &  frameFilenamePrefix,
Ceylan::Maths::Hertz  frameFrequency = 25 
) [virtual]

Tells whether the application should run interactively, in real time (if on is false), or if it should run in snapshot mode, with a virtual fixed framerate (as specified as frameFrequency), with logic and rendering taking all the time they need.

In this mode, even if the logic and the rendering tasks last for two hours for each virtual second, the resulting set of PNG files is made so that these files can be gathered to form an animation with, for instance, 25 frames per second. When this animation will be played, the logic will seem to have acted with respect to the planned framerate, as if in real time.

Parameters:
on tells whether frames are to be rendered to file (iff on), or if the application should run interactively.
frameFilenamePrefix determines which prefix will be used to name successive screenshots, in the form: 'frameFilenamePrefix'-n.png, n being the frame count of the animation.
frameFrequency tells how many frames should be rendered each second. At least 25 frames per second is recommended to be able to generate smooth animations.
See also:
OSDL user's guide to know how to simply create a MPEG video out of the set of image files that is produced in screenshot mode.
virtual void OSDL::Engine::Scheduler::setSimulationFrequency ( Ceylan::Maths::Hertz  frequency  )  [virtual]

Sets the simulation frequency, by evaluating the number of engine ticks to be associated to one simulation tick for frequency to be met.

Parameters:
frequency the new simulation frequency.
Exceptions:
SchedulingException if requested frequency is superior to engine frequency.
See also:
DefaultSimulationFrequency
void Scheduler::setStopCallback ( Ceylan::System::Callback  stopCallback = 0,
void *  callbackData = 0 
) [virtual]

Registers a new stop callback, which will be called each time the scheduler stops.

Parameters:
stopCallback the callback to register, which can be either a function or a static method; it can be set to null (0) to specify no stop callback is wanted.
callbackData the user-supplied data pointer that the stop callback will be given, if not null.

Definition at line 888 of file OSDLScheduler.cc.

References _stopCallback, and _stopCallbackData.

virtual void OSDL::Engine::Scheduler::setTimeSliceDuration ( Ceylan::System::Microsecond  engineTickDuration  )  [virtual]

Defines how many microseconds an engine tick should last, and updates accordingly the simulation and rendering ticks.

For example, an engine tick duration of 1000 microseconds defines a scheduling frequency of 1 kHz (1000 Hz). Then all scheduled events should then have a periodicity of at most 1000 Hz, probably far lower.

Parameters:
engineTickDuration the period of time between two scheduler elementary ticks, expressed in microseconds.
Note:
When changing this setting, in most cases the scheduled objects are to be changed or updated.
See also:
DefaultEngineTickDuration

Referenced by Scheduler().

void Scheduler::stop (  )  [virtual]

Requests the scheduler to stop its activities at the end of current engine tick.

Definition at line 879 of file OSDLScheduler.cc.

References _stopRequested.

Referenced by onScheduleFailure(), and StopExistingScheduler().

void Scheduler::StopExistingScheduler (  )  [static]

Deletes the shared scheduler, if any.

Allows notably to break out of the main loop.

Note:
As this function is static, it can be used as a callback triggered by the GUI, so that the program flow can go past the entering in the main loop.
Exceptions:
SchedulingException if no scheduler is in use.

Definition at line 1235 of file OSDLScheduler.cc.

References stop().

const string Scheduler::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

Definition at line 899 of file OSDLScheduler.cc.

References _currentEngineTick, _currentInputTick, _currentRenderingTick, _currentSimulationTick, _engineTickDuration, _idleCallback, _idleCallbackData, _idleCallbackMaxDuration, _idleCallbackMaxMeasuredDuration, _idleCallbackMinMeasuredDuration, _inputPeriod, _isRunning, _missedInputPollingTicks, _missedRenderingTicks, _missedSimulationTicks, _periodicSlots, _programmedActivated, _renderer, _renderingPeriod, _scheduleStartingMicrosecond, _scheduleStartingSecond, _screenshotMode, _screenshotPeriod, _simulationPeriod, OSDL::Video::Pixels::toString(), and OSDL::Rendering::Renderer::toString().

Referenced by describeProgrammedTicks(), onScheduleFailure(), scheduleBestEffort(), scheduleNoDeadline(), unregisterPeriodicalObject(), and unregisterProgrammedObject().

void Scheduler::unregisterPeriodicalObject ( PeriodicalActiveObject &  toUnregister  )  [virtual]

Unregisters specified periodical active object.

This method is intended to be called by objects that are periodic and that determined that they should unregister from the scheduler.

Parameters:
toUnregister the periodical active object to unregister from the scheduler.
Exceptions:
SchedulingException if the operation failed.

Definition at line 551 of file OSDLScheduler.cc.

References OSDL::Engine::PeriodicalActiveObject::getPeriod(), getPeriodicSlotFor(), OSDL::Engine::PeriodicSlot::removeFromSubslot(), and toString().

Referenced by OSDL::Engine::PeriodicalActiveObject::unregisterFromScheduler().

void Scheduler::unregisterProgrammedObject ( ProgrammedActiveObject &  toUnregister  )  [virtual]

Unregisters specified active object.

This method is intended to be called by objects that are peogrammed.

Parameters:
toUnregister the active object to unregister from the scheduler.
Exceptions:
SchedulingException if the operation failed.

Definition at line 648 of file OSDLScheduler.cc.

References _currentSimulationTick, _programmedActivated, OSDL::Engine::ProgrammedActiveObject::areProgrammedActivationsAbsolute(), OSDL::Engine::ActiveObject::getBirthTick(), OSDL::Engine::ProgrammedActiveObject::getProgrammedActivations(), toString(), OSDL::Engine::ProgrammedActiveObject::toString(), and OSDL::Video::Pixels::toString().

Referenced by OSDL::Engine::ProgrammedActiveObject::unregisterFromScheduler().

Member Data Documentation

Events::EngineTick OSDL::Engine::Scheduler::_currentEngineTick [protected]

Records the current engine tick.

Useful to determine how much time have elapsed since last schedule action.

Note:
Under normal circumstances (not too heavy load), the current engine tick multiplied by the engine tick duration should correspond to the current user time, with the offset of the library initialization time t0: (current time) - t0 = ( current engine tick ) * ( engine tick duration )

The scheduler has for purpose to enforce this property, but insufficient processing resources can make the engine time drift: hence one should not rely on this property being verified.

Therefore, this data member is the only one that is authoritative (the only actual value).

Definition at line 1390 of file OSDLScheduler.h.

Referenced by getCurrentEngineTick(), onScheduleFailure(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Events::RenderingTick OSDL::Engine::Scheduler::_currentInputTick [protected]

Records the current input tick.

Useful to determine how much time have elapsed since last input polling.

Note:
Under ideal circumstances (not too heavy load), the current input tick multiplied by the input tick duration should correspond to the current user time, with the offset of the library initialization time t0: (current time) - t0 = ( current input tick ) * ( engine input duration )

The scheduler has for purpose to enforce this property, but insufficient processing resources can make the input time drift: one should not rely on this property being verified. Therefore, this data member is the only one that is authoritative (the only actual value).

Definition at line 1465 of file OSDLScheduler.h.

Referenced by getCurrentInputTick(), onScheduleFailure(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Events::RenderingTick OSDL::Engine::Scheduler::_currentRenderingTick [protected]

Records the current rendering tick.

Useful to determine how much time have elapsed since last rendering action.

Note:
Under idel circumstances (not too heavy load), the current rendering tick multiplied by the rendering tick duration should correspond to the current user time, with the offset of the library initialization time t0: (current time) - t0 = ( current rendering tick ) * ( engine rendering duration )

The scheduler has for purpose to enforce this property, but insufficient processing resources can make the rendering time drift: one should not rely on this property being verified. Therefore, this data member is the only one that is authoritative (the only actual value).

Definition at line 1440 of file OSDLScheduler.h.

Referenced by getCurrentRenderingTick(), onScheduleFailure(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Events::SimulationTick OSDL::Engine::Scheduler::_currentSimulationTick [protected]

Records the current simulation tick.

Useful to determine how much time have elapsed since last simulation action.

Note:
Under ideal circumstances (not too heavy load), the current simulation tick multiplied by the simulation tick duration should correspond to the current user time, with the offset of the library initialization time t0: (current time) - t0 = ( current simulation tick ) * ( simulation tick duration )

The scheduler has for purpose to enforce this property, but insufficient processing resources can make the simulation time drift: one should not rely on this property being verified. Therefore, this data member is the only one that is authoritative (the only actual value).

Definition at line 1415 of file OSDLScheduler.h.

Referenced by getCurrentSimulationTick(), onScheduleFailure(), registerPeriodicalObject(), registerProgrammedObject(), scheduleBestEffort(), scheduleNoDeadline(), toString(), and unregisterProgrammedObject().

Ceylan::Maths::Hertz OSDL::Engine::Scheduler::_desiredInputFrequency [protected]

Records the user-defined input frequency.

Useful if the corresponding period had to be computed again after the engine tick duration changed.

Definition at line 1525 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Ceylan::Maths::Hertz OSDL::Engine::Scheduler::_desiredRenderingFrequency [protected]

Records the user-defined rendering frequency.

Useful if the corresponding period had to be computed again after the engine tick duration changed.

Definition at line 1514 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Ceylan::Maths::Hertz OSDL::Engine::Scheduler::_desiredScreenshotFrequency [protected]

Records the user-defined screenshot frequency, which is the targeted number of frames per second.

Useful if the corresponding period had to be computed again after the engine tick duration changed.

Definition at line 1265 of file OSDLScheduler.h.

Ceylan::Maths::Hertz OSDL::Engine::Scheduler::_desiredSimulationFrequency [protected]

Records the user-defined simulation frequency.

Useful if the corresponding period had to be computed again after the engine tick duration changed.

Definition at line 1503 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Ceylan::System::Microsecond OSDL::Engine::Scheduler::_engineTickDuration [protected]

Defines the duration in microseconds of an elementary scheduler tick.

Definition at line 1353 of file OSDLScheduler.h.

Referenced by computeEngineTickFromCurrentTime(), getNumberOfInputTicksFor(), getNumberOfRenderingTicksFor(), getNumberOfSimulationTicksFor(), getTimeSliceDuration(), scheduleBestEffort(), and toString().

Events::EventsModule* OSDL::Engine::Scheduler::_eventsModule [protected]

References the events module, if necessary.

Note:
Used mostly when the scheduler has to poll inputs during input tick.

Definition at line 1699 of file OSDLScheduler.h.

Referenced by schedule().

std::string OSDL::Engine::Scheduler::_frameFilenamePrefix [protected]

Records which prefix should be used to name numbered screenshot files.

The purpose of these files is mainly to be gathered in a movie (ex: MPEG).

Definition at line 1253 of file OSDLScheduler.h.

Ceylan::System::Callback OSDL::Engine::Scheduler::_idleCallback [protected]

The idle callback, if any, to be called by the scheduler.

Definition at line 1538 of file OSDLScheduler.h.

Referenced by onIdle(), scheduleBestEffort(), setIdleCallback(), and toString().

void* OSDL::Engine::Scheduler::_idleCallbackData [protected]

The data, if any, to provide to the idle callback.

Definition at line 1545 of file OSDLScheduler.h.

Referenced by onIdle(), setIdleCallback(), and toString().

Ceylan::System::Microsecond OSDL::Engine::Scheduler::_idleCallbackMaxDuration [protected]

An estimated upper bound of the duration of current idle callback.

Helps the scheduler to respect its expected pace while still issuing idle calls.

Definition at line 1557 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), setIdleCallback(), and toString().

Ceylan::System::Microsecond OSDL::Engine::Scheduler::_idleCallbackMaxMeasuredDuration [protected]

The highest measured actual duration for past idle callbacks.

Definition at line 1575 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and toString().

Ceylan::System::Microsecond OSDL::Engine::Scheduler::_idleCallbackMinMeasuredDuration [protected]

The smallest measured actual duration for past idle callbacks.

Definition at line 1566 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_idleCallsCount [protected]

Count the number of idle calls made during the current scheduler session.

Definition at line 1583 of file OSDLScheduler.h.

Referenced by onIdle(), and scheduleBestEffort().

std::list<ActiveObject *> OSDL::Engine::Scheduler::_initialRegisteredObjects [protected]

A list containing all the active objects (either periodical or programmed) that were registered before the scheduler is started.

Used to notify them of their birth time.

Definition at line 1313 of file OSDLScheduler.h.

Referenced by registerPeriodicalObject(), registerProgrammedObject(), and setInitialBirthTicks().

Events::Period OSDL::Engine::Scheduler::_inputPeriod [protected]

Duration between two successive input ticks, expressed in engine ticks.

Definition at line 1492 of file OSDLScheduler.h.

Referenced by getInputPollingTickCount(), getNumberOfInputTicksFor(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Scheduler * Scheduler::_internalScheduler = 0 [static, private]

The internal single instance of scheduler, if any.

Definition at line 1765 of file OSDLScheduler.h.

bool OSDL::Engine::Scheduler::_isRunning [protected]

Tells whether the scheduler is running.

Definition at line 1588 of file OSDLScheduler.h.

Referenced by registerPeriodicalObject(), registerProgrammedObject(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_missedInputPollingTicks [protected]

Records how many input ticks were missed since the scheduler was started.

Definition at line 1679 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_missedRenderingTicks [protected]

Records how many rendering ticks were missed since the scheduler was started.

Definition at line 1661 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_missedSimulationTicks [protected]

Records how many simulation ticks were missed since the scheduler was started.

Definition at line 1643 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and toString().

std::list<PeriodicSlot *> OSDL::Engine::Scheduler::_periodicSlots [protected]

A list containing all available periodic slots, ordered by increasing periods.

Note:
This is a list of pointers and not of PeriodicSlot instances since adding a new slot would otherwise result in a call to a copy constructor we do not want to define.

Definition at line 1301 of file OSDLScheduler.h.

Referenced by getPeriodicSlotFor(), returnPeriodicSlotFor(), toString(), and ~Scheduler().

std::map<Events::SimulationTick, ListOfProgrammedActiveObjects> OSDL::Engine::Scheduler::_programmedActivated [protected]

Map for programmed activations.

Each key of the map is a specific simulation tick, whereas its value is a list of all objects having requested to be scheduled at this particular simulation tick.

A map (namely, a hash table) has been prefered to a list sorted in chronological order (with std::set), since with a map, even if reading whether there are programmed triggers for the next simulation tick is slower (0(log n) instead of 0(1)), insertion times are much faster, (0(n.log n) instead of 0(n)).

As there may be numerous programmed triggers (ex: for playing sound delayed by distance), the map might be helpful here, although an ordered list might probably be more efficient.

Note that they might be both based on the same underlying data structure anyway, a black/red tree.

Definition at line 1342 of file OSDLScheduler.h.

Referenced by describeProgrammedTicks(), toString(), and unregisterProgrammedObject().

Ceylan::Uint32 OSDL::Engine::Scheduler::_recoveredInputPollingTicks [protected]

Records how many input ticks were recovered since the scheduler was started.

Definition at line 1670 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Ceylan::Uint32 OSDL::Engine::Scheduler::_recoveredRenderingTicks [protected]

Records how many rendering ticks were recovered since the scheduler was started.

Definition at line 1652 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Ceylan::Uint32 OSDL::Engine::Scheduler::_recoveredSimulationTicks [protected]

Records how many simulation ticks were recovered since the scheduler was started.

Definition at line 1634 of file OSDLScheduler.h.

Referenced by scheduleBestEffort().

Rendering::Renderer* OSDL::Engine::Scheduler::_renderer [protected]

References the renderer to be used, if any.

Definition at line 1707 of file OSDLScheduler.h.

Referenced by getRenderer(), hasRenderer(), schedule(), setRenderer(), toString(), and ~Scheduler().

Events::Period OSDL::Engine::Scheduler::_renderingPeriod [protected]

Duration between two successive rendering ticks, expressed in engine ticks.

Definition at line 1483 of file OSDLScheduler.h.

Referenced by getNumberOfRenderingTicksFor(), getRenderingTickCount(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_scheduleFailureCount [protected]

Records how many schedule failures were reported.

Happens when the delay bucket reaches its first threashold.

Definition at line 1688 of file OSDLScheduler.h.

Referenced by onScheduleFailure(), and scheduleBestEffort().

Ceylan::System::Microsecond OSDL::Engine::Scheduler::_scheduleStartingMicrosecond [protected]

Stores the microsecond when scheduling started.

Definition at line 1625 of file OSDLScheduler.h.

Referenced by computeEngineTickFromCurrentTime(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Ceylan::System::Second OSDL::Engine::Scheduler::_scheduleStartingSecond [protected]

Stores the second when scheduling started.

Definition at line 1618 of file OSDLScheduler.h.

Referenced by computeEngineTickFromCurrentTime(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

bool OSDL::Engine::Scheduler::_screenshotMode [protected]

Tells whether screenshot mode is activated (default: deactivated).

Note:
Screenshot mode is also known as 'no deadline' mode, as opposed to 'best effort' mode, which is in soft real time.

Definition at line 1241 of file OSDLScheduler.h.

Referenced by schedule(), and toString().

Events::Period OSDL::Engine::Scheduler::_screenshotPeriod [protected]

Stores the period corresponding to the planned framerate for the movie that would be generated, if screenshot mode is activated.

Movie periods, which are the duration between two successive screenshots, are expressed in engine ticks.

Definition at line 1278 of file OSDLScheduler.h.

Referenced by getScreenshotTickCount(), and toString().

Ceylan::Uint32 OSDL::Engine::Scheduler::_secondToEngineTick [protected]

Multiplicative factor that allows to convert seconds into engine ticks.

Note:
Useful to avoid overflow with conversions.

Definition at line 1364 of file OSDLScheduler.h.

Referenced by computeEngineTickFromCurrentTime().

Events::Period OSDL::Engine::Scheduler::_simulationPeriod [protected]

Duration between two successive simulation ticks, expressed in engine ticks.

Definition at line 1474 of file OSDLScheduler.h.

Referenced by getNumberOfSimulationTicksFor(), getSimulationTickCount(), scheduleBestEffort(), scheduleNoDeadline(), and toString().

Ceylan::System::Callback OSDL::Engine::Scheduler::_stopCallback [protected]

The stop callback, if any, to be called by the scheduler.

Definition at line 1603 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), scheduleNoDeadline(), and setStopCallback().

void* OSDL::Engine::Scheduler::_stopCallbackData [protected]

The data, if any, to provide to the stop callback.

Definition at line 1610 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), scheduleNoDeadline(), and setStopCallback().

bool OSDL::Engine::Scheduler::_stopRequested [protected]

Tells whether the scheduler has been requested to stop.

Definition at line 1596 of file OSDLScheduler.h.

Referenced by computeEngineTickFromCurrentTime(), scheduleBestEffort(), scheduleNoDeadline(), and stop().

bool OSDL::Engine::Scheduler::_subSecondSleepsAvailable [protected]

Tells whether sub-second sleeps can be used, to avoid monopolizing the CPU.

Definition at line 1731 of file OSDLScheduler.h.

Referenced by onIdle(), scheduleNoDeadline(), and Scheduler().

Video::VideoModule* OSDL::Engine::Scheduler::_videoModule [protected]

References the video module, if necessary.

Note:
Used mostly when the scheduler is not linked to a renderer. In this case, at each rendering tick the scheduler calls the redraw method of the video module. It allows scheduled objects to manage on their own the display, instead of using a full-blown dedicated renderer.

Definition at line 1722 of file OSDLScheduler.h.

Referenced by schedule().

const Ceylan::System::Microsecond OSDL::Engine::Scheduler::DefaultEngineTickDuration = 1000 [static]

Determines the default engine tick duration.

Note:
A value of 1000 implies a one millisecond scheduling, corresponding to a scheduling frequency of 1 kHz. Most interactive applications should be satisfied with this setting.

Definition at line 837 of file OSDLScheduler.h.

Referenced by scheduleBestEffort(), and Scheduler().

const Ceylan::Maths::Hertz OSDL::Engine::Scheduler::DefaultInputFrequency = 20 [static]

Determines the default frequency for input reading.

Note:
A value of 20 Hz (20 input polling per second) implies a 50 ms scheduling.

Definition at line 883 of file OSDLScheduler.h.

const Ceylan::Uint32 OSDL::Engine::Scheduler::DefaultMovieFrameFrequency = 25 [static]

By default, generated screenshots will be saved on the purpose of being gathered by a movie with 25 images per second.

See also:
OSDL users'guide to know how to generate such a movie.

Definition at line 872 of file OSDLScheduler.h.

const Ceylan::Maths::Hertz OSDL::Engine::Scheduler::DefaultRenderingFrequency = 40 [static]

Determines the default frequency for rendering.

Note:
A value of 40 Hz (40 frames per second) implies a 25 ms scheduling.

Definition at line 860 of file OSDLScheduler.h.

const Ceylan::Maths::Hertz OSDL::Engine::Scheduler::DefaultSimulationFrequency = 100 [static]

Determines the default frequency for logic (simulation).

Note:
A value of 100 Hz implies a 10 ms scheduling.

Definition at line 848 of file OSDLScheduler.h.

const Delay Scheduler::ShutdownBucketLevel = 1000000 [static, protected]

Threshold for the level of delay bucket, above which the scheduler will be stopped automatically.

Definition at line 1133 of file OSDLScheduler.h.

Referenced by onScheduleFailure(), and scheduleBestEffort().

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