cron: Add 'tickless' mode

 - time: Add function to round timestamp and timespans to milliseconds

Author: jasraj

src/cron.q

@@ -1,5 +1,5 @@
 // Cron Job Scheduler
-// Copyright (c) 2017 - 2019 Sport Trades Ltd
+// Copyright (c) 2017 - 2020 Sport Trades Ltd, 2021 Jaskirat Rajasansir
 
 // Documentation: https://github.com/BuaBook/kdb-common/wiki/cron.q
 
@@ -16,10 +16,10 @@
 /  @see .cron.status
 .cron.cfg.logStatus:1b;
 
-/ The supported run type for the cron system
-.cron.cfg.runners:()!();
-.cron.cfg.runners[`once]:`.cron.i.runOnce;
-.cron.cfg.runners[`repeat]:`.cron.i.runRepeat;
+/ The mode of operaton for the cron system. There are 2 supported modes:
+/  * ticking: Traditional timer system with the timer function running on a frequent interval
+/  * tickless: New approach to only 'tick' the timer  when the next job is due to run. Can reduce process load when infrequent jobs are run
+.cron.cfg.mode:`ticking;
 
 
 / Unique job ID for each cron job added
@@ -34,57 +34,73 @@
 `.cron.status upsert @[first .cron.status; `result; :; (::)];
 
 
-/ NOTE: The initialistion function will not overwrite .z.ts if it is already set.
+/ The supported run type for the cron system
+.cron.runners:(`symbol$())!`symbol$();
+.cron.runners[`once]:  `.cron.i.runOnce;
+.cron.runners[`repeat]:`.cron.i.runRepeat;
+
+/ The supported tick modes for the cron system
+.cron.supportedModes:(`symbol$())!`symbol$();
+.cron.supportedModes[`ticking]: `.cron.mode.ticking;
+.cron.supportedModes[`tickless]:`.cron.mode.tickless;
+
+/ The maximum supported timer interval as a timespan
+.cron.maxTimerAsTimespan:.convert.msToTimespan 0Wi - 1;
+
+/ One millisecond as a timespan (to not require calculation each time)
+.cron.oneMsAsTimespan:.convert.msToTimespan 1;
+
+
+/ NOTE: If '.z.ts' is defined at initialisation, the function will short-circuit and not configure the library
 .cron.init:{
     if[.ns.isSet `.z.ts;
         .log.if.warn "Timer function is already set. Cron will not override automatically";
         :(::);
     ];
 
     set[`.z.ts; .cron.ts];
-    .cron.enable[];
+    .cron.changeMode .cron.cfg.mode;
 
     if[not `.cron.cleanStatus in exec func from .cron.jobs;
         .cron.addRepeatForeverJob[`.cron.cleanStatus; (::); `timestamp$.time.today[]+1; 1D];
     ];
  };
 
 
-/ Starts the kdb timer to activate the cron system
-.cron.enable:{
-    if[0 < system"t";
-        :(::);
+/ Changes between the supported cron timer modes
+/  @param mode (Symbol) The cron timer mode to use
+/  @throws InvalidCronModeException If the mode is not one of the supported modes
+/  @see .cron.supportedModes
+.cron.changeMode:{[mode]
+    if[not mode in key .cron.supportedModes;
+        .log.if.error "Cron timer mode is invalid. Must be one of: ",.convert.listToString key .cron.supportedModes;
+        '"InvalidCronModeException";
     ];
 
-    .log.if.info "Enabling cron job scheduler [ Timer Interval: ",string[.cron.cfg.timerInterval]," ms ]";
-
-    .util.system "t ",string .cron.cfg.timerInterval;
-  };
+    .cron.cfg.mode:mode;
+    .cron.supportedModes[.cron.cfg.mode][];
+ };
 
-/ Disableds the kdb timer to deactivate the cron system
+/ Disables the kdb timer to deactivate the cron system
 .cron.disable:{
-    if[0 = system"t";
-        :(::);
-    ];
-
     .log.if.info "Disabling cron job scheduler";
     .log.if.warn " No scheduled jobs will be executed until cron is enabled again";
 
-    .util.system "t 0";
+    system "t 0";
  };
 
 / General job addition function. Adds a job to the cron system for execution
 /  @param func (Symbol) Symbol reference to the function to execute
 /  @param args () Any arguments that are required to execute the function. Pass generic null (::) for no arguments
-/  @param runType (Symbol) The type of cron job to add. See .cron.cfg.runners
-/  @param startTime (Timestamp) The first time the job will be run
-/  @param endTime (Timestamp) The time to finish a repeating job executing. Pass null (0Np) to repeat forever or for one time jobs
+/  @param runType (Symbol) The type of cron job to add. See .cron.runners
+/  @param startTime (Timestamp) The first time the job will be run. NOTE: Timestamp will be rounded to the nearest millisecond
+/  @param endTime (Timestamp) The time to finish a repeating job executing. Pass null (0Np) to repeat forever or for one time jobs. NOTE: Timestamp will be rounded to the nearest millisecond
 /  @param interval (Timespan) The interval at which repeating jobs should recur. Pass null (0Nn) for one time jobs
 /  @returns (Long) The ID of the new cron job
 /  @throws InvalidCronJobIntervalException If the interval specified is smaller than the cron interval
 /  @throws FunctionDoesNotExistFunction If the function for the cron job does not exist
 /  @throws ReferenceIsNotAFunctionException If the symbol reference for the function is not actually a function
-/  @throws InvalidCronRunTypeException If the run type specified is not present in .cron.cfg.runners
+/  @throws InvalidCronRunTypeException If the run type specified is not present in .cron.runners
 /  @throws InvalidCronJobTimeException If the start time specified is before the current time or the end time is before the start time
 .cron.add:{[func;args;runType;startTime;endTime;interval]
     if[not .ns.isSet func;
@@ -97,12 +113,20 @@
         '"ReferenceIsNotAFunctionException";
     ];
 
-    if[not runType in key .cron.cfg.runners;
-        .log.if.error "Invalid cron run type. Expecting one of: ",.convert.listToString key .cron.cfg.runners;
+    if[not runType in key .cron.runners;
+        .log.if.error "Invalid cron run type. Expecting one of: ",.convert.listToString key .cron.runners;
         '"InvalidCronRunTypeException";
     ];
 
-    if[startTime < .time.today[]+`second$.time.nowAsTime[];
+    if[not all .type.isTimestamp each (startTime; endTime);
+        .log.if.error "Invalid start time or end time. Must be a timestamp";
+        '"InvalidCronJobTimeException";
+    ];
+
+    startTime:.time.roundTimestampToMs startTime;
+    endTime:.time.roundTimestampToMs endTime;
+
+    if[startTime < .time.nowAsMsRoundedTimestamp[];
         .log.if.error "Cron job start time is in the past. Cannot add job";
         '"InvalidCronJobTimeException";
     ];
@@ -111,9 +135,9 @@
         .log.if.error "Cron job end time specified is before the start time. Cannot add job";
         '"InvalidCronJobTimeException";
     ];
-    
-    if[not[.util.isEmpty interval] & .cron.cfg.timerInterval > .convert.timespanToMs interval;
-        .log.if.error "Cron job repeat interval is shorter than the cron timer interval. Cannot add job";
+
+    if[(`ticking = .cron.cfg.mode) & not[.util.isEmpty interval] & .cron.cfg.timerInterval > .convert.timespanToMs interval;
+        .log.if.error "Cron job repeat interval is shorter than the cron timer interval (ticking). Cannot add job";
         '"InvalidCronJobIntervalException";
     ];
 
@@ -122,6 +146,10 @@
 
     `.cron.jobs upsert (jobId;func;args;runType;startTime;endTime;interval;startTime);
 
+    if[`tickless = .cron.cfg.mode;
+        .cron.i.setNextTick[];
+    ];
+
     :jobId;
  };
 
@@ -164,6 +192,10 @@
     ];
 
     update nextRunTime:0Wp from `.cron.jobs where id = jobId;
+
+    if[`tickless = .cron.cfg.mode;
+        .cron.i.setNextTick[];
+    ];
  };
 
 / Removes all entries from .cron.status and all jobs that will not run again. By default this is run at
@@ -177,7 +209,11 @@
 / The main cron function that is bound to .z.ts as part of the initialisation
 .cron.ts:{
     toRun:0!select id, runType from .cron.jobs where nextRunTime <= .time.now[];
-    { get[.cron.cfg.runners x`runType] x`id } each toRun;
+    .cron.runners[toRun`runType] @' toRun`id;
+
+    if[`tickless = .cron.cfg.mode;
+        .cron.i.setNextTick[];
+    ];
  };
 
 / Execution function for jobs that only run once
@@ -245,3 +281,48 @@
     :status;
  };
 
+/ Updates the 'tickless' timer tick based on the next run time. If no more cron jobs are scheduled to run, the timer will be disabled
+/ until a new job is added
+/  @see .cron.jobs
+/  @see .cron.oneMsAsTimespan
+/  @see .cron.maxTimerAsTimespan
+.cron.i.setNextTick:{
+    nextRun:exec min nextRunTime from .cron.jobs;
+
+    if[.type.isInfinite nextRun;
+        .log.if.trace "No active cron jobs scheduled. Disabling system timer";
+        system "t 0";
+        :(::);
+    ];
+
+    / Always make sure the next timer tick:
+    /  * Is not 0 (so accidentally disabled)
+    /  * Is not greater than max integer - 1
+    timer:.cron.maxTimerAsTimespan & .cron.oneMsAsTimespan | nextRun - .time.roundTimestampToMs .time.now[];
+    timerMs:.convert.timespanToMs timer;
+
+    if[timerMs = system "t";
+        :(::);
+    ];
+
+    system "t ",string timerMs;
+
+    .log.if.trace "Tickless cron timer updated [ Next Run: ",string[timer]," (",string[timerMs]," ms) ]";
+ };
+
+
+/ Enables the 'ticking' cron mode
+/ NOTE: Does not validate the configured ticking mode
+/  @see .cron.cfg.timerInterval
+.cron.mode.ticking:{
+    .log.if.info "Enabling cron job scheduler [ Mode: Ticking ] [ Timer Interval: ",string[.cron.cfg.timerInterval]," ms ]";
+    system "t ",string .cron.cfg.timerInterval;
+ };
+
+/ Enables the 'tickless' cron mode
+/ NOTE: Does not validate the configured ticking mode
+/  @see .cron.i.setNextTick
+.cron.mode.tickless:{
+    .log.if.info "Enabling cron job scheduler [ Mode: Tickless ]";
+    .cron.i.setNextTick[];
+ };

src/time.util.q

@@ -35,8 +35,26 @@
     :except[;".:"] string[.time.today[]],"_",string[ddmmss],"_",string millis;
  };
 
+/  @returns (Timestamp) Current time as timestamp but rounded to the nearest millisecond
+.time.nowAsMsRoundedTimestamp:{
+    :.time.today[] + .time.nowAsTime[];
+ };
+
 /  @returns (String) A file name friendly representation of the current date. Format is 'yyyymmdd'
 /  @see .time.today[]
 .time.todayForFileName:{
     :except[;"."] string .time.today[];
  };
+
+/ Rounds nanosecond precision timestamps and timespans to milliseconds
+.time.roundTimestampToMs:.time.roundTimespanToMs:{
+    if[not any .type[`isTimestamp`isTimespan] @\: x;
+        '"IllegalArgumentException";
+    ];
+
+    if[.type.isInfinite x;
+        :x;
+    ];
+
+    :.Q.t[abs type x]$1000000 * (`long$x) div 1000000;
+ };

src/type.q

@@ -5,7 +5,7 @@
 
 / All infinite values
 /  @see .type.isInfinite
-.type.const.infinites:raze (::;neg)@\:(0Wh;0Wi;0Wj;0We;0Wf;0Wp;0Wm;0Wd;0Wz;0Nn;0Wu;0Wv;0Wt);
+.type.const.infinites:raze (::;neg)@\:(0Wh;0Wi;0Wj;0We;0Wf;0Wp;0Wm;0Wd;0Wz;0Wn;0Wu;0Wv;0Wt);
 
 / Mapping of type name based on index in the list (matching .Q.t behaviour)
 .type.const.types:`mixedList`boolean`guid``byte`short`integer`long`real`float`character`symbol`timestamp`month`date`datetime`timespan`minute`second`time;