README.txt

   1 ELYSIA_CRON
   2 by Eric Berdondini (gotheric)
   3 <eric@void.it>
   4
   5 For installation instructions read INSTALL.TXT
   6 For module developers API documetation read API.TXT
   7
   8 -----------------------------------------------------------------------------
   9 FEATURES
  10 -----------------------------------------------------------------------------
  11
  12 Elysia Cron extends Drupal standard cron, allowing a fine grain control over
  13 each task and several ways to add custom cron jobs to your site.
  14
  15 - Set the timings and frequencies of each cron task (you can run some jobs every
  16   day at a specified hour, other only monthly and so on...).
  17   For each task you can simply choose between some frequently used options
  18   ("once a day", "once a month" ...), or use a powerful "linux crontab"-like
  19   syntax to set the accurate timings. You can even define your frequently used
  20   options to speed up site configuration.
  21 - Parallel execution of cron task: you can group jobs in channels and execute
  22   then simultaneously: so a task that takes a lot of time to execute won't block
  23   other tasks that need to be executed every 5 minutes...
  24 - You can disable all tasks, an entire channel or a single task.
  25 - Change the priority/order of task execution.
  26 - Manual force the execution of a cron tasks.
  27 - Detailed overview of cron status with time statistics for single tasks and
  28   channels.
  29
  30 - Powerful API for module developers: you can define extra cron tasks for your
  31   modules, each one with own default timings (site administrators can override
  32   them by configuration, other modules via hook_alter). Elysia Cron 2.0 gives a
  33   brand new API support (compatible with 1.0 version) with a lot of features.
  34 - Administrators can define custom jobs (call to functions with parameters), via
  35   the "script" option.
  36 - Several optimization for frequent cron calls and error handling.
  37 - Protection from external cron calling by cron_key or allowed host list.
  38
  39 Elysia has no dependencies with contributed modules, and doesn't need to patch
  40 the core: it can be used in minimal Drupal installation with only core modules.
  41 It also can be used in a Drupal install profile.
  42
  43 3rd party integration:
  44 - Ping feature, for external tracking services like host-tracker to tell whether
  45   cron is functioning properly on your site.
  46 - Drush support: you can call "drush elysia-cron" to manually run extended cron.
  47 - CTools support for exports/backup of task settings.
  48 - Features support.
  49
  50 -----------------------------------------------------------------------------
  51 USAGE EXAMPLES
  52 -----------------------------------------------------------------------------
  53
  54 Elysia cron is usually used in large sites that needs performance optimization.
  55
  56 - Avoid drupal peak loads by distributing heavy load tasks during quiet periods
  57   of the day: for example you may want to rebuild the XML Sitemap of your site
  58   at 2:00AM in the morning, where usually only a few people are visiting your
  59   site. You can even move some tasks to be executed only once a month (log
  60   rotation, old records expiry...).
  61
  62 - If you have tasks that should be executed very often, but don't want to
  63   execute ALL drupal cron tasks that often! For example, you may want to check
  64   for emails that needs to be sent to your users every 2 minutes. Standard cron
  65   is managed in a "monolithic" way, so even if you find out how to execute it
  66   every 2 minutes, you will end in having all cron tasks executed so often, with
  67   a lot of performance problems.
  68
  69 - Fine tune cron cache management : drupal cron will invalidate variable cache
  70   every cron run, and this is a great performance problem if you have a
  71   frequently called task. Elysia cron optimize cache management, and doesn't
  72   need to invalidate cache.
  73
  74 - Setup tasks that should be run at a precise time: for example if you want to
  75   send a SimpleNews newsletter every monday at 9:00AM, you can do it.
  76
  77 - Parallel execution: if you have a task that takes a lot of time to execute,
  78   you can setup a different channel for it so it won't block other tasks that
  79   need to be executed every 5 minutes.
  80
  81 - Turn off (disable) a cron task/feature you don't need.
  82
  83 - Debug system cron problems. If your cron does not terminate correctly you can
  84   use extended logging, see at each cron timings and disable task to track down
  85   the problem.
  86
  87 -----------------------------------------------------------------------------
  88 CHANNELS
  89 -----------------------------------------------------------------------------
  90
  91 Channels are groups of tasks. Each channel is a "parallel line" of execution
  92 (= multiple channels can be executed simultaneously).
  93 Tasks inside a channel will be executed sequentially (if they should).
  94
  95 WARNING: It's not recommended to create more than 2 or 3 channels.
  96 Every channel will increase the delay between each cron check (of the same
  97 channel), because each cron call will cycle between all channels.
  98 So, for example:
  99 If you have 1 channel it will be checked once a minute.
 100 If you have 2 channel each one will be checked every 2 minutes (almost usually,
 101 when the other one is running it will be checked once a minute).
 102 It you have 10 channels there will be a check every 10 minutes... if you have
 103 a job that should be executed every 5 minutes it won't do so!
 104
 105 -----------------------------------------------------------------------------
 106 EXPORT VIA CTOOLS/FEATURES MODULE
 107 -----------------------------------------------------------------------------
 108
 109 With 2.0 version of Elysia Cron you can use "Bulk Export" functionality of
 110 "Chaos Tools Suite" to export cron settings.
 111 To use it simply enable all modules, go to Structure > Bulk Exporter and
 112 select the tasks you want to export settings. You can also select all
 113 "elysia_cron" prefixed variables to export global options.
 114 Than generate the module.
 115
 116 The generated code will set the new defaults of elysia cron settings. This way
 117 you can simply enable it to use them, but you are free to override them in
 118 the future using the normal settings page.
 119 Note that if you want to delete all overrides, and return to exported settings,
 120 you should do a "reset to defaults" from elysia cron settings page.
 121
 122 You can also use "Features" module to create a Feature module will the settings
 123 you need.
 124 Note that if you want to delete the overridden settings it's preferable to use
 125 the "reset to defaults" elysia cron's button.
 126 You can use the "Revert components" Features's button, but this will reset also
 127 all cron statistics (if you are not interested in them you can freely use that
 128 button).
 129
 130 -----------------------------------------------------------------------------
 131 DRUSH SUPPORT
 132 -----------------------------------------------------------------------------
 133
 134 Elysia Cron 2.0 adds a simple support for Drush module.
 135
 136 You can execute the "elysia-cron" command to run cron.
 137
 138 -----------------------------------------------------------------------------
 139 RULES AND SCRIPT SYNTAX
 140 -----------------------------------------------------------------------------
 141
 142 1. FIELDS ORDER
 143 ---------------------------------
 144
 145  +---------------- minute (0 - 59)
 146  |  +------------- hour (0 - 23)
 147  |  |  +---------- day of month (1 - 31)
 148  |  |  |  +------- month (1 - 12)
 149  |  |  |  |  +---- day of week (0 - 6) (Sunday=0)
 150  |  |  |  |  |
 151  *  *  *  *  *
 152
 153 Each of the patterns from the first five fields may be either * (an asterisk),
 154 which matches all legal values, or a list of elements separated by commas
 155 (see below).
 156
 157 For "day of the week" (field 5), 0 is considered Sunday, 6 is Saturday (7 is
 158 an illegal value)
 159
 160 A job is executed when the time/date specification fields all match the current
 161 time and date. There is one exception: if both "day of month" and "day of week"
 162 are restricted (not "*"), then either the "day of month" field (3) or the "day
 163 of week" field (5) must match the current day (even though the other of the two
 164 fields need not match the current day).
 165
 166 2. FIELDS OPERATOR
 167 ---------------------------------
 168
 169 There are several ways of specifying multiple date/time values in a field:
 170
 171 * The comma (',') operator specifies a list of values, for example: "1,3,4,7,8"
 172 * The dash ('-') operator specifies a range of values, for example: "1-6", which
 173   is equivalent to "1,2,3,4,5,6"
 174 * The asterisk ('*') operator specifies all possible values for a field. For
 175   example, an asterisk in the hour time field would be equivalent to 'every hour'
 176   (subject to matching other specified fields).
 177 * The slash ('/') operator (called "step") can be used to skip a given number of
 178   values. For example, "*/3" in the hour time field is equivalent to
 179   "0,3,6,9,12,15,18,21".
 180
 181 3. EXAMPLES
 182 ---------------------------------
 183
 184  */15 * * * : Execute job every 15 minutes
 185  0 2,14 * * *: Execute job every day at 2:00 and 14:00
 186  0 2 * * 1-5: Execute job at 2:00 of every working day
 187  0 12 1 */2 1: Execute job every 2 month, at 12:00 of first day of the month OR
 188  at every monday.
 189
 190 4. SCRIPTS
 191 ---------------------------------
 192
 193 You can use the script section to easily create new jobs (by calling a php
 194 function) or to change the scheduling of an existing job.
 195
 196 Every line of the script can be a comment (if it starts with #) or a job
 197 definition.
 198
 199 The syntax of a job definition is:
 200 <-> [rule] <ctx:CONTEXT> [job]
 201
 202 (Tokens betweens [] are mandatory)
 203
 204 * <->: a line starting with "-" means that the job is DISABLED.
 205 * [rule]: a crontab schedule rule. See above.
 206 * <ctx:CHANNEL>: set the channel of the task.
 207 * [job]: could be the name of a supported job (for example: 'search_cron') or a
 208   function call, ending with ; (for example: 'process_queue();').
 209
 210 A comment on the line just preceding a job definition is considered the job
 211 description.
 212
 213 Remember that script OVERRIDES all settings on single jobs sections or channel
 214 sections of the configuration
 215
 216 5. EXAMPLE OF SCRIPT
 217 ---------------------------------
 218
 219 # Search indexing every 2 hours (i'm setting this as the job description)
 220 0 */2 * * * search_cron
 221
 222 # I'll check for module status only on sunday nights
 223 # (and this is will not be the job description, see the empty line below)
 224
 225 0 2 * * 0 update_status_cron
 226
 227 # Trackback ping process every 15min and on a channel called "net"
 228 */15 * * * * ctx:net trackback_cron
 229
 230 # Disable node_cron (i must set the cron rule even if disabled)
 231 - */15 * * * * node_cron
 232
 233 # Launch function send_summary_mail('test@test.com', false); every night
 234 # And set its description to "Send daily summary"
 235 # Send daily summary
 236 0 1 * * *  send_summary_mail('test@test.com', false);
 237
 238 -----------------------------------------------------------------------------
 239 CREDITS
 240 -----------------------------------------------------------------------------
 241
 242 Elysia cron is a part of the Elysia project (but could be used stand alone
 243 with no limitation).
 244
 245 Developing is sponsored by :
 246 Void Labs s.n.c
 247 http://www.void.it