NaviServer Built-in Commands – 5.1.0
ns_schedule - Scheduling Tcl scripts
These commands perform scheduling of Tcl scripts at various intervals. Script will run in separate thread as background procedures. This functionality is similar to Unix cron.
Schedules a script to be run after a certain interval. Returns the ID of the newly scheduled script. If -once is specified, then the script is run once and then unscheduled, otherwise it will continue to run every interval time periods. The time interval is based on the time instant, when the command was issued. When the time duration of a command takes long than the specified time interval for rescheduling, a warning message is generated and the command is issued 10ms after the long running one. So, the scheduled commands run always sequentially.
The interval can be specified with time units (per default seconds). If -thread is specified, then the script will be run in its own thread, otherwise it will run in the scheduler's thread. If the script is long-running, this may interfere with the running of other scheduled scripts, so long-running scripts should be run in their own threads.
When the optional arguments are provided, these are added to the command script to be executed.
% set id [ns_schedule_proc -once 60 { ns_log notice "this should run in 60 seconds" }]
123
Schedules a script to be run on a certain day of the week at a certain hour and minute of that day. Returns the ID of the newly scheduled script. The week starts on Sunday as day zero and runs to Saturday as day six. If -once is specified, then the script is run once and then unscheduled, otherwise it will continue to run every week on that day at that time. If -thread is specified, then the script will be run in its own thread, otherwise it will run in the scheduler's thread. If the script is long-running, this may interfere with the running of other scheduled scripts, so long-running scripts should be run in their own threads.
NOTE: day, hour and minute are specified in local time. Beware of Daylight Savings Time shifts affecting the time of day when the script will execute.
When the optional arguments are provided, these are added to the command script to be executed.
% set id [ns_schedule_weekly -once 2 5 35 { ns_log notice "It is now Tuesday at 5:35 AM." }]
123
% ns_unschedule_proc $id
Schedules a script to be run at a certain hour and minute of the day. Returns the ID of the newly scheduled script. If -once is specified, then the script is run once and then unscheduled, otherwise it will continue to run every day at that time. If -thread is specified, then the script will be run in its own thread, otherwise it will run in the scheduler's thread. If the script is long-running, this may interfere with the running of other scheduled scripts, so long-running scripts should be run in their own threads.
NOTE: hour and minute are specified in local time. Beware of Daylight Savings Time shifts affecting the time of day when the script will execute.
When the optional arguments are provided, these are added to the command script to be executed.
% set id [ns_schedule_daily -once 5 35 { ns_log notice "It is now 5:35 AM." }]
123
% ns_unschedule_proc $id
Pauses a scheduled script from running. This command pauses a scheduled script from running at its next scheduled time. Returns 1 on success, 0 on failure.
% set id [ns_schedule_daily 1 0 { ns_log notice "One AM and all is well. *gong*" }]
19
% ns_pause $id
1
Resumes a previously paused scheduled script. This command resumes scheduling of a previously paused script via ns_pause. Returns 1 on success, 0 on failure.
% set id [ns_schedule_daily 1 0 { ns_log notice "One AM and all is well. *gong*" }]
19
% ns_pause $id
1
% ns_resume $id
1
Executes a script after a time delay. This command executes a script in the background after interval time units. It does this by scheduling a one-shot event in the scheduler. Uncaught script errors will go to the server log. It returns an ID which can be used to unschedule the execution of the script (if interval hasn't elapsed) using ns_unschedule_proc.
The script when executed will run in the scheduler thread. If the script is long-running, this may interfere with the execution of other scheduled scripts, in which case ns_schedule_proc should be used instead of ns_after.
When the optional arguments are provided, these are added to the command script to be executed.
% ns_after 5s { ns_log notice "ns_after script executed" }
123
% set time 1s
% ns_after $time ns_log notice ns_after script executed after $time
Unschedules a previous scheduled script. The command returns a boolean result indicating success. When the id does not exist 0 is returned.
% ns_unschedule_proc $id 1
The scheduling commands use global defaults from the ns/parameters section of the NaviServer configuration file. These settings control scheduler thread recycling and logging of long-running scheduled jobs.
ns_section ns/parameters {
# Number of scheduled jobs processed by a scheduler thread before
# the thread exits and is replaced. A value of 0 disables automatic
# scheduler-thread recycling.
ns_param schedsperthread 1000
# Log scheduled jobs that run longer than this duration.
ns_param schedlogminduration 2s
}
These configuration parameters provide the defaults used by the scheduling subsystem. Individual scheduled jobs are still controlled by the options passed to the scheduling commands.
For the complete reference of global configuration parameters, see NaviServer configuration parameter reference.
When entries are written from scheduled procedures to the server log via ns_log these entries can be identified by the string
...[-sched:THREAD_NR:COUNTER_IN_THREAD:SCHED_ID-]...
where THREAD_NR refers to the nth thread, COUNTER_IN_THREAD is the nth job in this thread and the SCHED_ID refers to the ID of the scheduled script as returned by the ns_schedule* commands.