Author: jstephens
Date: 2006-09-25 20:04:44 +0200 (Mon, 25 Sep 2006)
New Revision: 3451
Log:
Updated description of event_scheduler server variable (event-scheduler
mysqld option).
Fixes Docs Bug #22408. (Thanks, Andrey!)
Modified:
trunk/mysqld-optvars/options.xml
trunk/refman-5.1/database-administration.xml
trunk/refman-5.1/events.xml
Modified: trunk/mysqld-optvars/options.xml
===================================================================
--- trunk/mysqld-optvars/options.xml 2006-09-25 15:19:39 UTC (rev 3450)
+++ trunk/mysqld-optvars/options.xml 2006-09-25 18:04:44 UTC (rev 3451)
Changed blocks: 2, Lines Added: 6, Lines Deleted: 2; 1112 bytes
@@ -4365,7 +4365,11 @@
<mysqloption id="event-scheduler">
<xrefto id="optvar_event-scheduler"/>
<name>event-scheduler</name>
- <shortdescription lang="en">Enable/disable the event scheduler</shortdescription>
+ <shortdescription lang="en">
+ Enable/disable and start/stop the event scheduler. Note that this
+ variable underwent singificant changes in behaviour and permitted
+ values in MySQL 5.1.11 and 5.1.12.
+ </shortdescription>
<section id="mysqld"/>
<opclass class="server"/>
<engines includes="all"/>
@@ -4376,7 +4380,7 @@
<optype class="mycnf"/>
<vartype class="server" format="event_scheduler" isdynamic="yes"/>
</types>
- <values vartype="boolean" platform="all"/>
+ <values vartype="string" platform="all"/>
<versions>
<manual version="5.1"/>
<introduced version="5.1.6"/>
Modified: trunk/refman-5.1/database-administration.xml
===================================================================
--- trunk/refman-5.1/database-administration.xml 2006-09-25 15:19:39 UTC (rev 3450)
+++ trunk/refman-5.1/database-administration.xml 2006-09-25 18:04:44 UTC (rev 3451)
Changed blocks: 1, Lines Added: 10, Lines Deleted: 2; 982 bytes
@@ -1339,9 +1339,17 @@
</para>
<para>
- Enable the event scheduler. This option was added in MySQL
- 5.1.6.
+ Enable or disable, and start or stop, the event scheduler.
+ This option was added in MySQL 5.1.6. Note that its
+ permitted values and behaviour changed in MySQL 5.1.11,
+ and again in MySQL 5.1.12.
</para>
+
+ <para>
+ For detailed information, see
+ <link linkend="events-event-scheduler-option">The
+ <option>event-scheduler</option> Option</link>.
+ </para>
</listitem>
<listitem>
Modified: trunk/refman-5.1/events.xml
===================================================================
--- trunk/refman-5.1/events.xml 2006-09-25 15:19:39 UTC (rev 3450)
+++ trunk/refman-5.1/events.xml 2006-09-25 18:04:44 UTC (rev 3451)
Changed blocks: 3, Lines Added: 166, Lines Deleted: 128; 16263 bytes
@@ -214,216 +214,252 @@
PROCESSLIST</literal>, as shown in the discussion that follows.
</para>
- <para>
+ <para id="events-event-scheduler-option">
The global variable <literal>event_scheduler</literal> determines
- whether the Event Scheduler is enabled on the server. Beginning
- with MySQL 5.1.11, it can have one of these 3 values, which affect
- event scheduling as follows:
+ whether the Event Scheduler is enabled and running on the server.
+ Beginning with MySQL 5.1.12, it has one of these 3 values, which
+ affect event scheduling as described here:
</para>
<itemizedlist>
<listitem>
<para>
- <literal>0</literal>: Event scheduling is OFF: The event
- scheduler thread does not run, and no scheduled events are
- executed. The <literal>event_scheduler</literal> variable
- cannot be set to this value while the server is running;
- instead, to turn off event scheduling altogether, you must
- start the server with
- <literal><option>--event-scheduler</option>=0</literal> or
- <literal><option>--event-scheduler</option>=OFF</literal>.
+ <literal>OFF</literal>: The Event Scheduler is stopped. The
+ event scheduler thread does not run, is not shown in the
+ output of <literal>SHOW PROCESSLIST</literal>, and no
+ scheduled events are executed. <literal>OFF</literal> is the
+ default value for <literal>event_scheduler</literal>.
</para>
<para>
- When the Event Scheduler is turned OFF, the event scheduler
- thread does not run, and so cannot be seen listed in the
- output of <literal>SHOW PROCESSLIST</literal>.
+ When the Event Scheduler is stopped
+ (<literal>event_scheduler</literal> is
+ <literal>OFF</literal>), it can be started by setting the
+ value of <literal>event_scheduler</literal> to
+ <literal>ON</literal>. (See next item.)
</para>
</listitem>
<listitem>
<para>
- <literal>1</literal>: The Event Scheduler is ON; the event
- scheduler thread runs and executes all scheduled events.
+ <literal>ON</literal>: The Event Scheduler is started; the
+ event scheduler thread runs and executes all scheduled events.
</para>
<para>
- When the Event Scheduler is in the ON state, it will appear to
- be sleeping:
+ When the Event Scheduler is <literal>ON</literal>, the event
+ scheduler thread is listed in the output of <literal>SHOW
+ PROCESSLIST</literal> as a daemon process, and its state is
+ represented as shown here:
</para>
<programlisting>
mysql> <userinput>SHOW PROCESSLIST\G</userinput>
*************************** 1. row ***************************
Id: 1
- User: event_scheduler
+ User: root
Host: localhost
db: NULL
-Command: Connect
+Command: Query
Time: 0
- State: Sleeping
- Info: NULL
+ State: NULL
+ Info: show processlist
*************************** 2. row ***************************
- Id: 52
- User: root
+ Id: 2
+ User: event_scheduler
Host: localhost
db: NULL
-Command: Query
- Time: 0
- State: NULL
- Info: SHOW PROCESSLIST
+Command: Daemon
+ Time: 3
+ State: Waiting for next activation
+ Info: NULL
2 rows in set (0.00 sec)
</programlisting>
- </listitem>
- <listitem>
<para>
- <literal>2</literal>: The Event Scheduler is SUSPENDED; the
- event scheduler thread runs, but it does not execute any
- scheduled events. This is the default value for
- <literal>event_scheduler</literal>.
+ Event scheduling can be stopped by setting the value of
+ <literal>event_scheduler</literal> to <literal>OFF</literal>.
</para>
+ </listitem>
+ <listitem>
<para>
- When the Event Scheduler is in the SUSPENDED state, this can
- be seen from the <literal>State</literal> column in the output
- of <literal>SHOW PROCESSLIST</literal> as shown here:
+ <literal>DISABLED</literal>: This value renders the Event
+ Scheduler non-operational. When the Event Scheduler is
+ <literal>DISABLED</literal>, the event scheduler thread does
+ not run (and so does not appear in the output of <literal>SHOW
+ PROCESSLIST</literal>).
</para>
-
-<programlisting>
-mysql> <userinput>SHOW PROCESSLIST\G</userinput>
-*************************** 1. row ***************************
- Id: 1
- User: event_scheduler
- Host: localhost
- db: NULL
-Command: Connect
- Time: 1
- State: Suspended
- Info: NULL
-*************************** 2. row ***************************
- Id: 52
- User: root
- Host: localhost
- db: NULL
-Command: Query
- Time: 0
- State: NULL
- Info: SHOW PROCESSLIST
-2 rows in set (0.00 sec)
-</programlisting>
</listitem>
</itemizedlist>
<para>
- Provided that the event scheduler thread has not been deactivated
- by starting the server with <option>--event-scheduler=0</option>,
- you can enable the execution of scheduled events by issuing either
- of the following two statements:
+ When the server is running<literal>event_scheduler</literal> can
+ be toggled between <literal>ON</literal> and
+ <literal>OFF</literal> (using <literal>SET</literal>). It is also
+ possible to use <literal>0</literal> for <literal>OFF</literal>,
+ and <literal>1</literal> for <literal>ON</literal> when setting
+ this variable. Thus, any of the following 4 statements can be used
+ in the <command>mysql</command> client to turn on the Event
+ Scheduler:
</para>
<programlisting>
+SET GLOBAL event_scheduler = ON;
+SET @@global.event_scheduler = ON;
SET GLOBAL event_scheduler = 1;
+SET @@global.event_scheduler = 1;
</programlisting>
<para>
- or
+ Similarly, any of these 4 statements can be used to turn off the
+ Event Scheduler:
</para>
<programlisting>
-SET @@global.event_scheduler = 1;
+SET GLOBAL event_scheduler = OFF;
+SET @@global.event_scheduler = OFF;
+SET GLOBAL event_scheduler = 0;
+SET @@global.event_scheduler = 0;
</programlisting>
<para>
- If event scheduling is enabled, you can suspend it by issuing
- either one of these two statements:
+ Although <literal>ON</literal> and <literal>OFF</literal> have
+ numeric equivalents, the value displayed for
+ <literal>event_scheduler</literal> by <literal>SELECT</literal> or
+ <literal>SHOW VARIABLES</literal> is always one of
+ <literal>OFF</literal>, <literal>ON</literal>, or
+ <literal>DISABLED</literal>. <emphasis><literal>DISABLED</literal>
+ has no numeric equivalent</emphasis>. For this reason,
+ <literal>ON</literal> and <literal>OFF</literal> are usually
+ preferred over <literal>1</literal> and <literal>0</literal> when
+ setting this variable.
</para>
+ <para>
+ Note that attempting to set <literal>event_scheduler</literal>
+ without specifying it as a global variable causes an error:
+ </para>
+
<programlisting>
-SET GLOBAL event_scheduler = 2;
+mysql< <userinput>SET @@event_scheduler = OFF;</userinput>
+<errortext>ERROR 1229 (HY000): Variable 'event_scheduler' is a GLOBAL
+variable and should be set with SET GLOBAL</errortext>
</programlisting>
<para>
- or
+ <emphasis role="bold">Important</emphasis>: It is not possible to
+ enable or disable the Event Scheduler when the server is running.
+ That is, you can change the value of
+ <literal>event_scheduler</literal> to <literal>DISABLED</literal>
+ — or from <literal>DISABLED</literal> to one of the other
+ permitted values for this option — only when the server is
+ stopped. Attempting to do so when the server is running fails with
+ an error.
</para>
+ <para>
+ To disable the event scheduler, use one of the following two
+ methods:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ As a command-line option when starting the server:
+ </para>
+
<programlisting>
-SET @@global.event_scheduler = 2;
+--event-scheduler=DISABLED
</programlisting>
+ </listitem>
- <para>
- <emphasis role="bold">Important</emphasis>: Once the server has
- been started with the event scheduler thread deactivated, the
- thread cannot be activated — that is, if the server was
- started with <option>--event-scheduler=0</option>, then
- <literal>event_scheduler</literal> cannot be set to
- <literal>1</literal> or <literal>2</literal> — without
- restarting <command>mysqld</command>. Similarly, if the server was
- started with the event scheduler thread running — that is,
- with <option>--event-scheduler=1</option> or
- <option>--event-schedule=2</option> — you cannot stop the
- event scheduler thread by issuing <literal>SET
- @@global.event_scheduler = 0;</literal>. Attempting to start or
- stop the event scheduler thread while the server is running causes
- an error, as shown here:
- </para>
+ <listitem>
+ <para>
+ In the server configuration file (<filename>my.cnf</filename>,
+ or <filename>my.ini</filename> on Windows systems), include
+ the line where it will be read by the server (for example, in
+ a <literal>[mysqld]</literal> section):
+ </para>
<programlisting>
-mysql> <userinput>SELECT @@global.event_scheduler;</userinput>
-+--------------------------+
-| @@global.event_scheduler |
-+--------------------------+
-| 2 |
-+--------------------------+
-1 row in set (0.00 sec)
-
-mysql> <userinput>SET @@global.event_scheduler = 0;</userinput>
-<errortext>ERROR 1231 (42000): Variable 'event_scheduler' can't be set to the value of '0'</errortext>
-mysql> <userinput>SET @@global.event_scheduler = 1;</userinput>
-Query OK, 0 rows affected (0.01 sec)
+event_scheduler=DISABLED
</programlisting>
+ </listitem>
- <para>
- Since <literal>event_scheduler</literal> is a global variable, you
- must have the <literal>SUPER</literal> privilege to set its value.
- </para>
+ </itemizedlist>
<para>
- The event scheduler thread cannot be killed. If you attempt to
- <literal>KILL</literal> the event scheduler thread, the effect is
- the same as suspending it. It can be re-enabled by setting the
- global <literal>event_scheduler</literal> variable to
- <literal>1</literal>, just as if you had previously set its value
- to <literal>2</literal>. The only way to stop this thread is by
- stopping the server.
+ To enable the Event Scheduler, restart the server without the
+ <option>--event-scheduler=<replaceable>DISABLED</replaceable></option>
+ command line option, or after removing or commenting out the line
+ containing <literal>event_scheduler=DISABLED</literal> in the
+ server configuration file, as appropriate. Alternatively, you can
+ use <literal>ON</literal> (or <literal>1</literal>) or
+ <literal>OFF</literal> (or <literal>0</literal>) in place of the
+ <literal>DISABLED</literal> value when starting the server.
</para>
<para>
<emphasis role="bold">Note</emphasis>: You can issue
event-manipulation statements when
- <literal>event_scheduler</literal> is set to <literal>0</literal>
- or <literal>2</literal>. No warnings or errors are generated in
- such cases (provided that the statements are themselves valid).
+ <literal>event_scheduler</literal> is set to
+ <literal>DISABLED</literal>. No warnings or errors are generated
+ in such cases (provided that the statements are themselves valid).
However, scheduled events cannot execute until this variable is
- set to <literal>1</literal>. Once this has been done, the event
- scheduler thread executes all events whose scheduling conditions
- are satisfied.
+ set to <literal>ON</literal> (or <literal>1</literal>). Once this
+ has been done, the event scheduler thread executes all events
+ whose scheduling conditions are satisfied.
</para>
<para>
- <emphasis role="bold">Note</emphasis>: Prior to MySQL 5.1.11,
- <literal>event_scheduler</literal> could take one of only the 2
- values <literal>0</literal>|<literal>OFF</literal> or
- <literal>1</literal>|<literal>ON</literal>, the default value
- being <literal>0</literal>|<literal>OFF</literal>. It was also
+ In MySQL 5.1.11, <literal>event_scheduler</literal> behaved as
+ follows: this variable could take one of the values
+ <literal>0</literal> (or <literal>OFF</literal>),
+ <literal>1</literal> (or <literal>ON</literal>), or
+ <literal>2</literal>. Setting it to <literal>0</literal> turned
+ event scheduling off, so that the event scheduler thread did not
+ run; the <literal>event_scheduler</literal> variable could not be
+ set to this value while the server was running. Setting it to
+ <literal>1</literal> so that the event scheduler thread ran and
+ executed scheduled events. In this state, the event scheduler
+ thread appeared to be sleeping when viewed with <literal>SHOW
+ PROCESSLIST</literal>. When <literal>event_scheduler</literal> was
+ set to <literal>2</literal> (which was the default value), the
+ Event Scheduler was considered to be <quote>suspended</quote>; the
+ event scheduler thread ran and could be seen in the output of
+ <literal>SHOW PROCESSLIST</literal> (where
+ <literal>Suspended</literal> was displayed in the
+ <literal>State</literal> column), but did not execute any
+ scheduled events. The value of <literal>event_scheduler</literal>
+ could be changed only between <literal>1</literal> (or
+ <literal>ON</literal>) and <literal>2</literal> while the server
+ was running. Setting it to <literal>0</literal> (or
+ <literal>OFF</literal>) required a server restart, as did changing
+ its value from <literal>0</literal> (or <literal>OFF</literal>) to
+ <literal>1</literal> (or <literal>ON</literal>) or
+ <literal>2</literal>.
+ </para>
+
+ <para>
+ Prior to MySQL 5.1.11, <literal>event_scheduler</literal> could
+ take one of only the 2 values
+ <literal>0</literal>|<literal>OFF</literal> or
+ <literal>1</literal>|<literal>ON</literal>, and the default value
+ was <literal>0</literal>|<literal>OFF</literal>. It was also
possible to start and stop the event scheduler thread while the
- MySQL server was running. For information concerning the reasons
- for this change in behaviour, see Bug #17619.
+ MySQL server was running.
</para>
<para>
+ For more information concerning the reasons for these changes in
+ behaviour, see Bug #17619.
+ </para>
+
+ <para>
For SQL statements used to create, alter, and drop events, see
<xref linkend="events-syntax"/>.
</para>
@@ -431,8 +467,10 @@
<para>
MySQL 5.1.6 and later provides an <literal>EVENTS</literal> table
in the <literal>INFORMATION_SCHEMA</literal> database. This table
- can be queried to find out about the events which exist on the
- server. See <xref linkend="events-metadata"/>.
+ can be queried to obtian information about scheduled events which
+ have been defined on the server. See
+ <xref linkend="events-metadata"/>, and
+ <xref linkend="events-table"/>, for more information.
</para>
<para>
@@ -782,11 +820,11 @@
</listitem>
</itemizedlist>
-
+
<para>
The <literal>ON SCHEDULE</literal> clause may not use
subselects. This is true for both <literal>CREATE
- EVENT</literal> and <literal>ALTER EVENT</literal> statements.
+ EVENT</literal> and <literal>ALTER EVENT</literal> statements.
</para>
<para>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r3451 - in trunk: mysqld-optvars refman-5.1 | jon | 25 Sep |
