Progress

Moose Development/Moose/Core/Scheduler.lua

@@ -1,36 +1,43 @@
 --- This module contains the SCHEDULER class.
 --
--- 1) @{Core.Scheduler#SCHEDULER} class, extends @{Core.Base#BASE}
--- =====================================================
--- The @{Core.Scheduler#SCHEDULER} class models time events calling given event handling functions.
+-- # 1) @{Core.Scheduler#SCHEDULER} class, extends @{Core.Base#BASE}
+-- 
+-- The @{Core.Scheduler#SCHEDULER} class creates schedule.
 --
--- 1.1) SCHEDULER constructor
--- --------------------------
--- The SCHEDULER class is quite easy to use:
+-- ## 1.1) SCHEDULER constructor
+-- 
+-- The SCHEDULER class is quite easy to use, but note that the New constructor has variable parameters:
 --
---  * @{Core.Scheduler#SCHEDULER.New}: Setup a new scheduler and start it with the specified parameters.
+--  * @{Core.Scheduler#SCHEDULER.New}( nil ): Setup a new SCHEDULER object, which is persistently executed after garbage collection.
+--  * @{Core.Scheduler#SCHEDULER.New}( Object ): Setup a new SCHEDULER object, which is linked to the Object. When the Object is nillified or destroyed, the SCHEDULER object will also be destroyed and stopped after garbage collection.
+--  * @{Core.Scheduler#SCHEDULER.New}( nil, Function, FunctionArguments, Start, ... ): Setup a new persistent SCHEDULER object, and start a new schedule for the Function with the defined FunctionArguments according the Start and sequent parameters.
+--  * @{Core.Scheduler#SCHEDULER.New}( Object, Function, FunctionArguments, Start, ... ): Setup a new SCHEDULER object, linked to Object, and start a new schedule for the Function with the defined FunctionArguments according the Start and sequent parameters.
+--
+-- ## 1.2) SCHEDULER timer stopping and (re-)starting.
 --
--- 1.2) SCHEDULER timer stop and start
--- -----------------------------------
 -- The SCHEDULER can be stopped and restarted with the following methods:
 --
---  * @{Core.Scheduler#SCHEDULER.Start}: (Re-)Start the scheduler.
---  * @{Core.Scheduler#SCHEDULER.Stop}: Stop the scheduler.
+--  * @{Core.Scheduler#SCHEDULER.Start}(): (Re-)Start the schedules within the SCHEDULER object. If a CallID is provided to :Start(), only the schedule referenced by CallID will be (re-)started.
+--  * @{Core.Scheduler#SCHEDULER.Stop}(): Stop the schedules within the SCHEDULER object. If a CallID is provided to :Stop(), then only the schedule referenced by CallID will be stopped.
 --
--- 1.3) Reschedule new time event
--- ------------------------------
--- With @{Core.Scheduler#SCHEDULER.Schedule} a new time event can be scheduled.
+-- ## 1.3) Create a new schedule
+-- 
+-- With @{Core.Scheduler#SCHEDULER.Schedule}() a new time event can be scheduled. This function is used by the :New() constructor when a new schedule is planned.
 --
 -- ===
 --
 -- ### Contributions: 
 -- 
---   * Mechanist : Concept & Testing
+--   * FlightControl : Concept & Testing
 -- 
 -- ### Authors: 
 -- 
 --   * FlightControl : Design & Programming
 -- 
+-- ### Test Missions:
+-- 
+--   * SCH - Scheduler
+-- 
 -- ===
 --
 -- @module Scheduler
@@ -55,19 +62,24 @@ SCHEDULER = {
 -- @param #number RandomizationFactor Specifies a randomization factor between 0 and 1 to randomize the RepeatSecondsInterval.
 -- @param #number StopSeconds Specifies the amount of seconds when the scheduler will be stopped.
 -- @return #SCHEDULER self
+-- @return #number The ScheduleID of the planned schedule.
 function SCHEDULER:New( TimeEventObject, TimeEventFunction, TimeEventFunctionArguments, StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds )
   local self = BASE:Inherit( self, BASE:New() )
   self:F2( { StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds } )
 
-  self:Schedule( TimeEventObject, TimeEventFunction, TimeEventFunctionArguments, StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds )
+  local ScheduleID = nil
+  
+  if TimeEventFunction then
+    ScheduleID = self:Schedule( TimeEventObject, TimeEventFunction, TimeEventFunctionArguments, StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds )
+  end
 
-  return self
+  return self, ScheduleID
 end
 
 --function SCHEDULER:_Destructor()
 --  --self:E("_Destructor")
 --
---  _TIMERDISPATCHER:RemoveSchedule( self.CallID )
+--  _SCHEDULEDISPATCHER:RemoveSchedule( self.CallID )
 --end
 
 --- Schedule a new time event. Note that the schedule will only take place if the scheduler is *started*. Even for a single schedule event, the scheduler needs to be started also.
@@ -79,7 +91,7 @@ end
 -- @param #number RepeatSecondsInterval Specifies the interval in seconds when the scheduler will call the event function.
 -- @param #number RandomizationFactor Specifies a randomization factor between 0 and 1 to randomize the RepeatSecondsInterval.
 -- @param #number StopSeconds Specifies the amount of seconds when the scheduler will be stopped.
--- @return #SCHEDULER self
+-- @return #number The ScheduleID of the planned schedule.
 function SCHEDULER:Schedule( TimeEventObject, TimeEventFunction, TimeEventFunctionArguments, StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds )
   self:F2( { StartSeconds, RepeatSecondsInterval, RandomizationFactor, StopSeconds } )
   self:T3( { TimeEventFunctionArguments } )
@@ -87,7 +99,7 @@ function SCHEDULER:Schedule( TimeEventObject, TimeEventFunction, TimeEventFuncti
 
   self.TimeEventObject = TimeEventObject
   
-  self.Schedules[#self.Schedules+1] = _TIMERDISPATCHER:AddSchedule( 
+  local ScheduleID = _SCHEDULEDISPATCHER:AddSchedule( 
     self, 
     TimeEventFunction,
     TimeEventFunctionArguments,
@@ -96,51 +108,37 @@ function SCHEDULER:Schedule( TimeEventObject, TimeEventFunction, TimeEventFuncti
     RandomizationFactor,
     StopSeconds
   )
-
-  return self
-end
-
---- (Re-)Starts the scheduler.
--- @param #SCHEDULER self
--- @return #SCHEDULER self
-function SCHEDULER:Start()
-  self:F2()
-
-  if self.RepeatSecondsInterval ~= 0 then
-    self.Repeat = true
-  end
   
-  if self.StartSeconds then
-    self:T( { self.StartSeconds } )
-    self.Schedules[#self.Schedules+1] = _TIMERDISPATCHER:AddSchedule( 
-      self, 
-      self.TimeEventObject,
-      self.TimeEventFunction,
-      self.TimeEventFunctionArguments,
-      self.StartSeconds,
-      self.RepeatSecondsInterval,
-      self.RandomizationFactor,
-      self.StopSeconds
-    )
-  end
-  
-  return self
+  self.Schedules[#self.Schedules+1] = ScheduleID
+
+  return ScheduleID
 end
 
---- Stops the scheduler.
+--- (Re-)Starts the schedules or a specific schedule if a valid ScheduleID is provided.
 -- @param #SCHEDULER self
--- @return #SCHEDULER self
-function SCHEDULER:Stop()
-  self:F2( self.TimeEventObject )
+-- @param #number ScheduleID (optional) The ScheduleID of the planned (repeating) schedule.
+function SCHEDULER:Start( ScheduleID )
+  self:F3( { ScheduleID } )
 
-  self.Repeat = false
-  if self.ScheduleID then
-    self:E( "Stop Schedule" )
-    timer.removeFunction( self.ScheduleID )
-  end
-  self.ScheduleID = nil
+  _SCHEDULEDISPATCHER:Start( self, ScheduleID )
+end
 
-  return self
+--- Stops the schedules or a specific schedule if a valid ScheduleID is provided.
+-- @param #SCHEDULER self
+-- @param #number ScheduleID (optional) The ScheduleID of the planned (repeating) schedule.
+function SCHEDULER:Stop( ScheduleID )
+  self:F3( { ScheduleID } )
+
+  _SCHEDULEDISPATCHER:Stop( self, ScheduleID )
+end
+
+--- Removes a specific schedule if a valid ScheduleID is provided.
+-- @param #SCHEDULER self
+-- @param #number ScheduleID (optional) The ScheduleID of the planned (repeating) schedule.
+function SCHEDULER:Remove( ScheduleID )
+  self:F3( { ScheduleID } )
+
+  _SCHEDULEDISPATCHER:Remove( self, ScheduleID )
 end