README.txt 12 KB

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