[FEATURE] Migrate sysext manuals to reST
[Packages/TYPO3.CMS.git] / typo3 / sysext / scheduler / Documentation / Overview / Index.rst
1 .. ==================================================
2 .. FOR YOUR INFORMATION
3 .. --------------------------------------------------
4 .. -*- coding: utf-8 -*- with BOM.
5
6 .. include:: ../Includes.txt
7
8
9
10 .. _overview:
11
12 Overview
13 --------
14
15
16 .. _why-a-scheduling-tool:
17
18 Why a scheduling tool?
19 ^^^^^^^^^^^^^^^^^^^^^^
20
21 When running and maintaining a complex system like TYPO3, there are a
22 number of tasks that need to be automated or executed in the small
23 hours, when no one is around to press the button. Indeed quite a few
24 extensions come with some command-line scripts meant to be run
25 regularly using cron jobs. When each of these scripts need their
26 separate entry in the server's crontab, maintenance complexity
27 increases, as well as the cost of migration. Furthermore there's no
28 simple way to keep an overview of and manage these tasks inside TYPO3.
29
30 The Scheduler aims to address this issue.
31
32
33 .. _tasks-management:
34
35 Tasks management
36 ^^^^^^^^^^^^^^^^
37
38 Scripts can be developed as Scheduler tasks by extending a base class
39 provided by the Scheduler. They can then be registered with the
40 Scheduler. At that point it becomes possible to set up a schedule for
41 them by using the Scheduler's BE module.
42
43 The BE module provides an overview of all scheduled tasks and some
44 indication of their status, e.g. are they currently running or are
45 they late, did something wrong happen during last execution, etc. It
46 is also possible to manually start the execution of tasks from the BE
47 module.
48
49
50 .. _tasks-execution:
51
52 Tasks execution
53 ^^^^^^^^^^^^^^^
54
55 The Scheduler provides a command-line tool to be run by TYPO3's
56 command-line dispatcher. Only this script needs to be registered in
57 the server's cron tab for all other recurring tasks to be executed.
58 Indeed every time the Scheduler is launched by the cron daemon, it
59 will look for all tasks that are due (or overdue) and execute them.
60
61 When a task is executed by the Scheduler it is marked as being
62 executed in the corresponding database record (in the field called
63 "serialized\_executions"). When the task has finished running, the
64 execution is removed from the database record. This mechanism makes it
65 possible to know that a given task is currently running and also helps
66 prevent multiple executions. Indeed it may be that a task requires
67 more time to run than the frequency it is set up for. In such a case a
68 new run may be started which is not always desirable. It is possible
69 to deny such parallel (or multiple) executions.
70
71
72 .. _follow-up:
73
74 Follow-up
75 ^^^^^^^^^
76
77 Whenever a task starts or ends a message is written to TYPO'3 system
78 log (viewable in the Admin Tools > Log module). A message is also
79 written when a parallel execution has been blocked. This makes it
80 possible to follow what happens, since the main purpose of the
81 Scheduler is to run things when nobody is watching.
82
83 A task that fails may report on the reasons for failure using
84 exceptions. Such a message will be logged in the Scheduler's database
85 table and will be displayed in the BE module.
86
87 There's no default output to the command-line as scheduled tasks are
88 designed to run in the background.
89
90
91 .. _glossary:
92
93 Glossary
94 ^^^^^^^^
95
96 A few terms need to be defined more precisely:
97
98 - **Task** : this word is used quite generally throughout this document,
99 sometimes to cover different meanings. A task is really a piece of
100 code that does a precise task and can be registered with the Scheduler
101 in order to execute that piece of code at a precise time, recurrently
102 or not.
103
104 - **Task class** : this is the type of task. The "test" task is one
105 particular task class. Its function is to send an email. The "sleep"
106 task is another task class.
107
108 - **Registered task** : an instance of a task class that has been
109 registered with the Scheduler. A given task class may be registered
110 several times, for example if it needs to be executed with different
111 parameters.
112