OSDLScheduler.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the OSDL library.
 *
 * The OSDL library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The OSDL library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and of the GNU General Public License along with the OSDL library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#ifndef OSDL_SCHEDULER_H_
#define OSDL_SCHEDULER_H_




// for ListOfActiveObjects, SchedulingException, etc.:
#include "OSDLEngineCommon.h"         
#include "OSDLEvents.h"               // for SimulationTick
#include "OSDLPeriodicSlot.h"         // for PeriodicSlot



// for inheritance, SingletonException, Hertz and time units:
#include "Ceylan.h"                   



#include <string>
#include <list>
#include <map>




namespace OSDL
{



    namespace Events
    {
    
    
        // Scheduler is managed by the event module.
        class EventsModule ;
        
    }



    namespace Rendering
    {
    
    
        // The scheduler may use a dedicated renderer for rendering concerns.
        class Renderer ;
        
    }

    
    
    namespace Video
    {
    
        /*
         * The scheduler fallbacks to the video module if no renderer is 
         * being used.
         *
         */
        class VideoModule ;
        
    }
    
    
    
    namespace Engine 
    {
    
        
        
        // The scheduler schedules active objects.
        class ActiveObject ;



        // The scheduler uses periodic slots for periodically activated objects.
        class PeriodicSlot ;
        
        
        
                
        class OSDL_DLL Scheduler : public Ceylan::Object
        {
        
        
            public:
            
            
            
                /*
                 * Constructors are not public, the Get*Scheduler factories
                 * should be used instead.
                 *
                 */
                 
                 
                
                virtual bool hasRenderer() const ;



                virtual Rendering::Renderer & getRenderer() const ;



                virtual void setRenderer( Rendering::Renderer & newRenderer ) ;
                
                
                
                virtual void setScreenshotMode( bool on, 
                    const std::string & frameFilenamePrefix, 
                    Ceylan::Maths::Hertz frameFrequency = 25 ) ;
                
                
                
                virtual void setTimeSliceDuration( 
                    Ceylan::System::Microsecond engineTickDuration ) ;


    
                virtual Ceylan::System::Microsecond getTimeSliceDuration() 
                    const ;
                
                
                
                virtual void setSimulationFrequency( 
                    Ceylan::Maths::Hertz frequency ) ;


                
                virtual Events::Period getSimulationTickCount() const ;
                
                
                
                virtual void setRenderingFrequency( 
                        Ceylan::Maths::Hertz frequency ) ;


                
                virtual Events::Period getRenderingTickCount() const ;
            
            
                
                virtual void setScreenshotFrequency( 
                    Ceylan::Maths::Hertz frequency ) ;

                
                
                virtual Events::Period getScreenshotTickCount() const ;
                
                
                
                virtual void setInputPollingFrequency( 
                    Ceylan::Maths::Hertz frequency ) ;



                virtual Events::Period getInputPollingTickCount() const ;

                
                
                virtual void setIdleCallback( 
                    Ceylan::System::Callback idleCallback = 0 , 
                    void * callbackData = 0,
                    Ceylan::System::Microsecond callbackExpectedMaxDuration = 0
                ) ;
                
                
                
                virtual Events::EngineTick getCurrentEngineTick() const ;
                
                
                
                virtual Events::SimulationTick getCurrentSimulationTick() 
                    const ;
                
                
                
                virtual Events::RenderingTick getCurrentRenderingTick() const ;
                
                
                
                virtual Events::InputTick getCurrentInputTick() const ;
                
                
                
                
                
                
                
                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 ) ;
                    
                                
                
                virtual void unregisterPeriodicalObject( 
                    PeriodicalActiveObject & toUnregister ) ;


                
                virtual void registerProgrammedObject( 
                    ProgrammedActiveObject & toRegister ) ;
                        
                
                        
                virtual void unregisterProgrammedObject( 
                    ProgrammedActiveObject & toUnregister ) ;
                        
                        
                        
                virtual void schedule() ;
                
                            
                                
                virtual void stop() ;
                
                
                
                virtual void setStopCallback( 
                    Ceylan::System::Callback stopCallback = 0 , 
                    void * callbackData = 0 ) ;
                
                 
                                        
                virtual const std::string toString( 
                    Ceylan::VerbosityLevels level = Ceylan::high ) const ;





                // Static section.



                static Scheduler & GetExistingScheduler() ;


            
                static Scheduler & GetScheduler() ;



                static void DeleteExistingScheduler() ;
        
        
        
                static void DeleteScheduler() ;
        
        
        
                static void StopExistingScheduler() ;
        
    
                    
                static const Ceylan::System::Microsecond
                    DefaultEngineTickDuration = 1000 ;
                    
                    
                    
                static const Ceylan::Maths::Hertz DefaultSimulationFrequency 
                    = 100 ;
                    
                    
                    
                static const Ceylan::Maths::Hertz DefaultRenderingFrequency 
                    = 40 ;
                    
                    
                    
                static const Ceylan::Uint32 DefaultMovieFrameFrequency = 25 ;
                
                
                
                static const Ceylan::Maths::Hertz DefaultInputFrequency = 20 ;
                    




                    
            protected:
            


                explicit Scheduler() ;
                
                
                
                virtual ~Scheduler() throw() ;



                virtual void scheduleBestEffort() ;
                


                virtual void scheduleNoDeadline( bool pollInputs = true ) ;
                
                
                
                virtual Events::EngineTick computeEngineTickFromCurrentTime() ;



                virtual void scheduleSimulation( 
                    Events::SimulationTick current ) ;



                virtual void scheduleProgrammedObjects( 
                    Events::SimulationTick current ) ;



                virtual void schedulePeriodicObjects( 
                    Events::SimulationTick currentSimulationTick ) ;



                virtual void scheduleRendering( 
                    Events::RenderingTick currentRenderingTick ) ;
                     
                     
                     
                virtual void scheduleInput( 
                    Events::InputTick currentInputTick ) ;



                virtual void scheduleProgrammedObjectList( 
                    Events::RenderingTick currentSimulationTick, 
                    ListOfProgrammedActiveObjects & objectList ) ;
                    
                    
                    
                virtual void onSimulationSkipped( 
                    Events::SimulationTick skipped ) ;
                
                

                virtual void onRenderingSkipped( 
                    Events::RenderingTick skipped ) ;
                                


                virtual void onInputSkipped( Events::InputTick skipped ) ;
                    
                                
                
                virtual void onIdle() ;



                static const Delay ShutdownBucketLevel ;
                
                
                
                virtual void onScheduleFailure( Delay currentBucket ) ;


                
                virtual void programTriggerFor( 
                    ProgrammedActiveObject & objectToProgram,
                    Events::SimulationTick targetTick ) ;
                


                virtual PeriodicSlot & getPeriodicSlotFor( 
                    Events::Period period ) ;



                virtual PeriodicSlot & returnPeriodicSlotFor( 
                    Events::Period period ) ;
                
                

                /*
                 * Sets the birth times of objects that already exist at
                 * start-up.
                 *
                 * The dynamically created ones will have their birth time
                 * set at registration time.
                 *
                 */
                virtual void setInitialBirthTicks(
                    Events::SimulationTick birthSimulationTick ) ;
                


                std::string describeProgrammedTicks() const ; 




                // Variable section.
                
                
                
                bool _screenshotMode ;      
                
                
                
                std::string _frameFilenamePrefix ;      

                
                
                Ceylan::Maths::Hertz _desiredScreenshotFrequency ;
                
                
                
                 Events::Period _screenshotPeriod ;     
                

/* 
 * Takes care of the awful issue of Windows DLL with templates.
 *
 * @see Ceylan's developer guide and README-build-for-windows.txt 
 * to understand it, and to be aware of the associated risks. 
 * 
 */
#pragma warning( push )
#pragma warning( disable: 4251 )
            
            
                std::list<PeriodicSlot *> _periodicSlots ; 
                
            
            
                std::list<ActiveObject *> _initialRegisteredObjects ; 
                
                
                
                std::map<Events::SimulationTick, ListOfProgrammedActiveObjects>
                    _programmedActivated ;      
                
                
#pragma warning( pop ) 

                
                Ceylan::System::Microsecond _engineTickDuration ;
                
                
                
                Ceylan::Uint32 _secondToEngineTick ;
                
                
                
                Events::EngineTick _currentEngineTick ;
                
            
                
                Events::SimulationTick _currentSimulationTick ;
                
                
                
                Events::RenderingTick _currentRenderingTick ;
                
                
                
                Events::RenderingTick _currentInputTick ;
                
                
                
                Events::Period _simulationPeriod ;
                
                
                
                Events::Period _renderingPeriod ;
                
                
                
                Events::Period _inputPeriod ;
                
                
                
                Ceylan::Maths::Hertz _desiredSimulationFrequency ;
                
                
                
                Ceylan::Maths::Hertz _desiredRenderingFrequency ;
        
        
        
                Ceylan::Maths::Hertz _desiredInputFrequency ;



                
                // Idle callback section.
                
                

                Ceylan::System::Callback _idleCallback ;
                        
                            
                void * _idleCallbackData ;              
        
        
                
                Ceylan::System::Microsecond _idleCallbackMaxDuration ;
        
        
        
                Ceylan::System::Microsecond _idleCallbackMinMeasuredDuration ;
        
        
        
                Ceylan::System::Microsecond _idleCallbackMaxMeasuredDuration ;
        
                
                Ceylan::Uint32 _idleCallsCount ;
        
        
        
                bool _isRunning ;
                
                
                
                // Stop section.
        
        
                bool _stopRequested ;
        
        
                Ceylan::System::Callback _stopCallback ;
        
                                
                void * _stopCallbackData ;              
        
        
        
                Ceylan::System::Second _scheduleStartingSecond ;
                
                
                Ceylan::System::Microsecond _scheduleStartingMicrosecond ;      
        
        
        
                Ceylan::Uint32 _recoveredSimulationTicks ;
        
        
        
                Ceylan::Uint32 _missedSimulationTicks ;
        
        
        
                Ceylan::Uint32 _recoveredRenderingTicks ;
        
        
        
                Ceylan::Uint32 _missedRenderingTicks ;
        
        
        
                Ceylan::Uint32 _recoveredInputPollingTicks ;
        
        
        
                Ceylan::Uint32 _missedInputPollingTicks ;
        
        
                Ceylan::Uint32 _scheduleFailureCount ;
        
        

                Events::EventsModule * _eventsModule ;
                
                
        
                Rendering::Renderer * _renderer ;
        
        
        
                Video::VideoModule * _videoModule ;
                
                
                
                bool _subSecondSleepsAvailable ;
                 
                
                
                 
            private:
            
            
            
                explicit Scheduler( const Scheduler & source ) ;
            
            
            
                Scheduler & operator = ( const Scheduler & source ) ;
                    
                            
                
                static Scheduler * _internalScheduler ;
            
                
        } ;
        

    }

}



#endif // OSDL_SCHEDULER_H_

---