expresser

<!DOCTYPE html> <html> <head> <title>cron.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1>cron.coffee</h1> <div class="toc"> <h3>Table of Contents</h3> <ol> <li> <a class="source" href="index.html"> index.coffee </a> </li> <li> <a class="source" href="app.html"> app.coffee </a> </li> <li> <a class="source" href="cron.html"> cron.coffee </a> </li> <li> <a class="source" href="database.html"> database.coffee </a> </li> <li> <a class="source" href="downloader.html"> downloader.coffee </a> </li> <li> <a class="source" href="events.html"> events.coffee </a> </li> <li> <a class="source" href="firewall.html"> firewall.coffee </a> </li> <li> <a class="source" href="imaging.html"> imaging.coffee </a> </li> <li> <a class="source" href="logger.html"> logger.coffee </a> </li> <li> <a class="source" href="mailer.html"> mailer.coffee </a> </li> <li> <a class="source" href="settings.html"> settings.coffee </a> </li> <li> <a class="source" href="sockets.html"> sockets.coffee </a> </li> <li> <a class="source" href="utils.html"> utils.coffee </a> </li> </ol> </div> </div> <h2 id="expresser-cron">EXPRESSER CRON</h2> Handle scheduled cron jobs. You can use intervals (seconds) or specific times to trigger jobs, and the module will take care of setting the proper timers. Jobs are added using “job” objects with id, schedule, callback and other options.  <div class='highlight'><pre>class Cron events = require "./events.coffee" fs = require "fs" lodash = require "lodash" logger = require "./logger.coffee" moment = require "moment" path = require "path" settings = require "./settings.coffee" utils = require "./utils.coffee"</pre></div> @property [Array] The jobs collection, please do not edit this object manually! <div class='highlight'><pre> jobs: []</pre></div> <h2 id="constructor-and-init">CONSTRUCTOR AND INIT</h2> Cron constructor. <div class='highlight'><pre> constructor: -> @setEvents() if settings.events.enabled</pre></div> Bind event listeners. <div class='highlight'><pre> setEvents: => events.on "cron.start", @start events.on "cron.stop", @stop events.on "cron.add", @add events.on "cron.remove", @remove</pre></div> Init the cron manager. If <code>loadOnInit</code> setting is true, the <code>cron.json</code> file will be parsed and loaded straight away (if there’s one). <div class='highlight'><pre> init: (options) => logger.debug "Cron.init" @load true if settings.cron.loadOnInit</pre></div> Load jobs from the <code>cron.json</code> file. If <code>autoStart</code> is true, it will automatically call the <code>start</code> method after loading. @param [String] filename Path to the JSON file containing jobs, optional, default is “cron.json”. @param [Object] options Options to be passed when loading cron jobs. @option options [String] basePath Sets the base path of modules when requiring them. @option options [Boolean] autoStart If true, call “start” after loading. <div class='highlight'><pre> load: (filename, options) => logger.debug "Cron.load", filename, options</pre></div> Set default options. <div class='highlight'><pre> options = {} if not options? options = lodash.defaults options, {autoStart: false, basePath: ""} if lodash.isBoolean filename filename = null options.autoStart = filename if not filename? or filename is false or filename is "" filename = "cron.json" doNotWarn = true</pre></div> Get full path to the passed json file. <div class='highlight'><pre> filepath = utils.getFilePath filename basename = path.basename filepath</pre></div> Found the cron.json file? Read it. <div class='highlight'><pre> if filepath? cronJson = fs.readFileSync filepath, {encoding: settings.general.encoding} cronJson = utils.minifyJson cronJson</pre></div> Iterate jobs, but do not add if job’s <code>enabled</code> is false. <div class='highlight'><pre> for key, data of cronJson module = require(options.basePath + key) for d in data if not d.enabled? or d.enabled cb = module[d.callback] job = d job.module = key job.id = key + "." + d.callback job.callback = cb @add job else logger.debug "Cron.load", filename, key, d.callback, "Enabled is false. Skip!"</pre></div> Start all jobs automatically if <code>autoStart</code> is true. <div class='highlight'><pre> @start() if options.autoStart logger.info "Cron.load", "#{basename} loaded." else if not doNotWarn logger.warn "Cron.load", "#{basename} not found."</pre></div> <h2 id="methods">METHODS</h2> Start the specified cron job. If no <code>id</code> is specified, all jobs will be started. A filter can also be passed as an object. For example to start all jobs for the module “email”, use start({module: “email”}). @param [String] idOrFilter The job id or filter, optional (if not specified, start everything). <div class='highlight'><pre> start: (idOrFilter) => if not idOrFilter? logger.info "Cron.start", "All jobs" arr = @jobs if lodash.isString idOrFilter or lodash.isNumber idOrFilter logger.info "Cron.start", idOrFilter arr = lodash.find @jobs, {id: idOrFilter.toString()} else logger.info "Cron.start", idOrFilter arr = lodash.find @jobs, idOrFilter if not arr? or arr.length < 1 logger.debug "Cron.start", "Job #{idOrFilter} does not exist. Abort!" else for job in arr clearTimeout job.timer if job.timer? setTimer job</pre></div> Stop the specified cron job. If no <code>id</code> is specified, all jobs will be stopped. A filter can also be passed as an object. For example to stop all jobs for the module “mymodule”, use stop({module: “mymodule”}). @param [String] idOrFilter The job id or filter, optional (if not specified, stop everything). <div class='highlight'><pre> stop: (idOrFilter) => if not idOrFilter? logger.info "Cron.stop", "All jobs" arr = @jobs if lodash.isString idOrFilter or lodash.isNumber idOrFilter logger.info "Cron.stop", idOrFilter arr = lodash.find @jobs, {id: idOrFilter.toString()} else logger.info "Cron.stop", idOrFilter arr = lodash.find @jobs, idOrFilter if not arr? or arr.length < 1 logger.debug "Cron.stop", "Job #{idOrFilter} does not exist. Abort!" else for job in arr clearTimeout job.timer if job.timer? job.timer = null</pre></div> Add a scheduled job to the cron, passing an <code>id</code> and <code>job</code>. You can also pass only the <code>job</code> if it has an id property. @param [String] id The job ID, optional, overrides job.id in case it has one. @param [Object] job The job object. @option job [String] id The job ID, optional. @option job [Integer, Array] schedule If a number assume it’s the interval in seconds, otherwise a times array. @option job [Method] callback The callback (job) to be triggered. @option job [Boolean] once If true, the job will be triggered only once no matter which schedule it has. @return [Object] Returns {error, job}, where job is the job object and error is the error message (if any). <div class='highlight'><pre> add: (id, job) => logger.debug "Cron.add", id, job if id? and not job? job = id id = null</pre></div> If no <code>id</code> is passed, try getting it directly from the <code>job</code> object. <div class='highlight'><pre> id = job.id if not id?</pre></div> Throw error if no <code>id</code> was provided or callback is invalid. <div class='highlight'><pre> if not id? or id is "" errorMsg = "No 'id' was passed. Abort!" logger.error "Cron.add", errorMsg return {error: errorMsg}</pre></div> Throw error if job callback is not a valid function. <div class='highlight'><pre> if not lodash.isFunction job.callback errorMsg = "The job #{id} callback is not a valid function. Abort!" logger.error "Cron.add", errorMsg return {error: errorMsg}</pre></div> Find existing job. <div class='highlight'><pre> existing = lodash.find @jobs, {id: id}</pre></div> Handle existing jobs. <div class='highlight'><pre> if existing? if settings.cron.allowReplacing clearTimeout existing.timer if existing.timer? existing.timer = null else errorMsg = "Job #{id} already exists and 'allowReplacing' is false. Abort!" logger.error "Cron.add", errorMsg return {error: errorMsg}</pre></div> Set <code>startTime</code> and <code>endTime</code> if not set. <div class='highlight'><pre> job.startTime = moment 0 if not job.startTime? job.endTime = moment 0 if not job.endTime?</pre></div> Only create the timer if <code>autoStart</code> is not false. <div class='highlight'><pre> setTimer job if job.autoStart isnt false</pre></div> Add to the jobs list. <div class='highlight'><pre> job.id = id @jobs.push job return {job: job}</pre></div> Remove and stop a current job. If job does not exist, a warning will be logged. @param [String] id The job ID. <div class='highlight'><pre> remove: (id) => existing = lodash.find @jobs, {id: id}</pre></div> Job exists? <div class='highlight'><pre> if not existing? logger.debug "Cron.remove", "Job #{id} does not exist. Abort!" return false</pre></div> Clear timer and remove job from array. <div class='highlight'><pre> clearTimeout existing.timer if existing.timer? @jobs.splice existing</pre></div> <h2 id="helpers">HELPERS</h2> Helper to get the timeout value (ms) to the next job callback. <div class='highlight'><pre> getTimeout = (job) -> now = moment() nextDate = moment()</pre></div> If <code>schedule</code> is not an array, parse it as integer / seconds. <div class='highlight'><pre> if lodash.isNumber job.schedule or lodash.isString job.schedule timeout = moment().add("s", job.schedule).valueOf() - now.valueOf() else minTime = "99:99:99" nextTime = "99:99:99"</pre></div> Get the next and minimum times from <code>schedule</code>. <div class='highlight'><pre> for sc in job.schedule minTime = sc if sc < minTime nextTime = sc if sc < nextTime and sc > nextDate.format("HH:mm:ss")</pre></div> If no times were found for today then set for tomorrow, minimum time. <div class='highlight'><pre> if nextTime is "99:99:99" nextDate = nextDate.add "d", 1 nextTime = minTime</pre></div> Return the timeout. <div class='highlight'><pre> arr = nextTime.split ":" dateValue = [nextDate.year(), nextDate.month(), nextDate.date(), parseInt(arr[0]), parseInt(arr[1]), parseInt(arr[2])] timeout = moment(dateValue).valueOf() - now.valueOf() return timeout</pre></div> Helper to prepare and get a job callback function. <div class='highlight'><pre> getCallback = (job) -> callback = -> logger.debug "Cron", "Job #{job.id} trigger." job.timer = null job.startTime = moment() job.endTime = moment() job.callback job</pre></div> Only reset timer if once is not true. <div class='highlight'><pre> setTimer job if not job.once</pre></div> Return generated callback. <div class='highlight'><pre> return callback</pre></div> Helper to get a timer / interval based on the defined options. <div class='highlight'><pre> setTimer = (job) -> callback = getCallback job</pre></div> Get the correct schedule / timeout value. <div class='highlight'><pre> schedule = job.schedule schedule = moment.duration(schedule).asMilliseconds() if not lodash.isNumber schedule</pre></div> Make sure timer is not running. <div class='highlight'><pre> clearTimeout job.timer if job.timer?</pre></div> Set the timeout based on the defined schedule. <div class='highlight'><pre> timeout = getTimeout job job.timer = setTimeout callback, timeout job.nextRun = moment().add "ms", timeout logger.debug "Cron.setTimer", job.id, timeout</pre></div> <h2 id="singleton-implementation-">Singleton implementation.</h2> <div class='highlight'><pre>Cron.getInstance = -> @instance = new Cron() if not @instance? return @instance module.exports = exports = Cron.getInstance()</pre></div> <div class="fleur">h</div> </div> </div> </body> </html>