.. currentmodule:: scheduler
.. _scheduler:

Module Scheduler
================

This module contains functions to execute functions(tasks) at a regular interval.


Scheduled tasks
---------------

Scheduled tasks are tasks that are executed at a predefined interval with the function :py:meth:`scheduler.add_task`. This interval can be configured in the similar way as cronjobs are configured. 
A interval description is built up out of 5 fields separated by white spaces that represent a set of times at which to execute the task
The function runs when the current date matches the interval description. A interval description looks like this: ::

    # ┌───────────── second (0 - 59)
    # │ ┌───────────── minute (0 - 59)
    # │ │ ┌───────────── hour (0 - 23)
    # │ │ │ ┌───────────── day of the month (1 - 31)
    # │ │ │ │ ┌───────────── day of the week (1 - 7) (Monday to Sunday)
    # │ │ │ │ │
    # │ │ │ │ │
    # │ │ │ │ │
    # * * * * *

Special characters can be used to select a range or multiple values for a field. The following special characters are allowed.

- ``*`` Asterisk - The asterisk is used to select all allowed values for that field.
- ``,`` Comma - The comma defines a list of values. For example 0,14,29,44 in the first field would mean seconds 0, 14, 29, and 44.
- ``-`` Dash - The dash defines a range of values. For example 5-10 indicates all minutes between 5 and 10, inclusive. (5, 6, 7, 8, 9, 10)

.. list-table:: Example intervals
   :widths: 20 80
   :header-rows: 1

   * - Expression 
     - Meaning 
   * - ``* * * * *``
     - Every second
   * - ``0 * * * *``
     - Every minute at hh:mm:00
   * - ``2 * * * *``
     - Every minute at hh:mm:02
   * - ``0 0 * * *`` 
     - Every hour at hh:00:00
   * - ``5 1 * * *`` 
     - Every hour at hh:01:05
   * - ``0 0 0 * *`` 
     - Every day at 00:00:00
   * - ``0,29 * * * *`` 
     - Every 30 seconds
   * - ``0 0,10,20,30,40,50 * * *`` 
     - Every 10 minutes
   * - ``0 30 9 * 7``
     - Every sunday at 9:30:00
   * - ``0 0 12 1 *``
     - Every first day of the month at 12:00:00
   * - ``0 0 9-17 * 1-6``
     - Hourly between 9:00:00 and 17:00:00 except for Sunday



Methods
-------
.. method:: scheduler.schedule_task(func: function, interval: string, name: string) -> None

   Add a task to the scheduler to execute at a interval. 

    - ``func`` The function to execute. Pass the function without calling it (don't use the round braces). The function should not have any parameters and the definition should be async.
    - ``interval`` The interval string as explained above.
    - ``name`` The name of the task, used for logging.

.. method:: scheduler.triggered_task(func: function, name, event=None) -> Event

   Add a task that can be triggered by an event from for example another task. A pre-existing event object can be used to trigger multiple tasks by the same event.

    - ``func`` The function to execute. Pass the function without calling it (don't use the round braces). The function should not have any parameters and the definition should be async.
    - ``name`` The name of the task, used for logging.
    - ``event`` The event to trigger the task with, a new event object is created if this parmeter is empty.

   Return value: The event object used

.. method:: sheduler.start() -> None

   Start the scheduler, executing all the added tasks at the specified interval.

.. method:: scheduler.trigger_event(event: Event) -> None

    Trigger an event, starting all associated tasks.

     - ``event`` The event object to trigger

.. method:: sleep_between_tasks(pre_sleep: func, post_sleep: func) -> None
   
   Enable light sleep in between tasks running. The device will wake-up 200ms before the next scheduled task.

.. method:: sleep(sec: integer) -> None

   Let the task sleep for x seconds, giving control back to the scheduler.

.. method:: sleep_ms(ms: integer) -> None

   Let the task sleep for x milliseconds, giving control back to the scheduler. 

Examples
--------

The following code has 3 Tasks, 1 that runs every 5 seconds and 2 triggered tasks, that are started by the first task. ::

    import omc048
    import scheduler
    import micropython
    import utime

    led = omc048.LED()
    event = None

    async def flash_red():
        print('led.colour(\'red\') start: {0}'.format(utime.ticks_ms()))
        led.colour('red')
        await scheduler.sleep_ms(700)
        led.off()
        print('led.colour(\'red\') stop: {0}'.format(utime.ticks_ms()))
        global event
        scheduler.trigger_event(event)

    async def flash_blue():
        print('led.colour(\'blue\') start: {0}'.format(utime.ticks_ms()))
        led.colour('blue')
        await scheduler.sleep_ms(20)
        led.off()
        print('led.colour(\'blue\') stop: {0}'.format(utime.ticks_ms()))


    async def print_something():
        print("fooo")
        await scheduler.sleep_ms(50)
        print("bar")
        micropython.mem_info()


    scheduler.schedule_task(flash_red, '0,5,10,15,20,25,30,35,40,45,50,55 * * * *', 'red')
    event = scheduler.triggered_task(flash_blue, 'blue')
    scheduler.triggered_task(print_something, 'printing', event)

    scheduler.start()