= Scheduler =
[[TOC]]
The scheduler is used for asynchronous tasks (not from a user request to the web server).

Some example uses are for daily maintenance and for processing and sending messages.

The Eden scheduler is a wrapper to the [http://web2py.com/books/default/chapter/29/4#Scheduler-%28experimental%29 web2py scheduler].

== New Task ==
To create a new function in `/models/tasks.py` for your new task, and point to it by setting a value in the `tasks` dictionary, e.g.,

{{{
#!python
def my_task(*args, **vars):
    return result

tasks["my_task"] = my_task
}}}

Notes:
* args/vars need to be simple Text, Integer or JSON structures
* The scope for a task varies depending on whether the scheduler is running (new request) or not (same request as pushes it async)
 * therefore assume the least scope (new request) & ensure that testing is done with a real scheduler running
* If a task needs authorisation, then need to pass in the user_id & do {{{current.auth.s3_impersonate(user_id)}}}
* If a task modifies the database, then need to do a {{{db.commit()}}}
== Recurring Tasks ==
Adding a schedule for a recurring task can be done by using [http://pub.nursix.org/eden/s3/s3.s3task.S3Task-class.html#schedule_task s3task.schedule_task()] in `/models/zzz_1st_run.py`.

{{{
#!python
s3task.schedule_task(
	"my_task",
	args=[
		"foo",
	],
	vars={
		"bar": "cha",
	},
	period=300, # every 5 minutes
	repeats=0 # repeat forever
)
}}}

Note that recurring tasks don't normally use credentials.

== Asynchronous ==
The scheduler can be used to 'push work async' so that the browser page returns to the user, whilst the task then runs in the background.

Tasks run in this way normally run as the user who initiated the task.

e.g.:
{{{
def stats_data_onapprove(row):
    """
       When a stats_data record is approved then the related stats_aggregate
       fields need to be updated so that the results are kept up to date.

       This is done async as this can take some time
    """
    current.s3task.async("stats_update_time_aggregate",
                         args = [row.data_id],
                         )
}}}

== Launch Scheduler ==
{{{
cd web2py
python web2py.py -K eden
}}}

Note that this cannot be used with SQLite as it needs simultaneous access to the database.

See Also:
* [http://web2py.com/books/default/chapter/29/13#Start-the-scheduler-as-a-Linux-service-%28upstart%29 Linux Service]
* [http://web2py.com/books/default/chapter/29/13#Using-nssm-to-run-as-a-Windows-service Win32 Service]

== Debugging ==
A task can be run through the [DeveloperGuidelines/Eclipse Eclipse] debugger using this script:
* https://github.com/flavour/eden/blob/master/static/scripts/tools/run_scheduler_tasks.py

Note: The Task must have an entry in the recurring tasks table: db.scheduler_task & this is where the args/vars are read from

== See Also ==
* UserGuidelines/Admin/Scheduler