Scheduler-API

There are two ways to access the API

1. Directly

   Use it the following way to access the api, if you have no access to the sh object in your method or function:

   # to get access to the object instance:
   from lib.scheduler import Scheduler
   scheduler = Scheduler.get_instance()
   
   # to access a method (eg. to trigger a logic):
   scheduler.trigger(...)
   

2. Through the main SmartHome object

   If you have access to the sh object in your method or function, you can use the following way:

   # to access a method (eg. to trigger a logic):
   sh.scheduler.trigger(...)
   

The API is implemented through the following library:

lib.scheduler

exception lib.scheduler.LeaveLogic

Bases: Exception

exception lib.scheduler.TaskCancelled

Bases: BaseException

Raised inside a running logic whose cancellation was requested.

Derives from BaseException, so except Exception in logic code does not swallow it; try/finally blocks still run.

class lib.scheduler.RunningTask(thread_ident, task_type, name, started, started_at, runtime_warn=0, trigger=None, warnings_logged=0, task_id=0, runtime_cancel=0, cancel_requested_at=None, cancel_requests=0)

Bases: object

A scheduler task currently executing on a worker thread.

Variablen:

• thread_ident – threading.get_ident() of the worker thread running the task

• task_type – kind of task object - logic, item (cycle/cron/autotimer) or method

• name – scheduler name of the task

• started – time.monotonic() at task start, basis for runtime calculation

• started_at – wall-clock time at task start, for display

• runtime_warn – seconds after which a runtime warning is logged; 0 disables warnings

• trigger – trigger dict of a logic (by, source, source_details, dest, value), None for other types

• warnings_logged – number of runtime warnings logged so far

• task_id – unique id of this task run, assigned by the registry; distinguishes runs on the same thread

• runtime_cancel – seconds after which cancellation is requested automatically; 0 disables

• cancel_requested_at – time.monotonic() of the first cancellation request, None if never requested

• cancel_requests – number of cancellation requests so far

thread_ident: int

task_type: Literal['logic', 'item', 'method']

name: str

started: float

started_at: datetime

runtime_warn: float = 0

trigger: dict | None = None

warnings_logged: int = 0

task_id: int = 0

runtime_cancel: float = 0

cancel_requested_at: float | None = None

cancel_requests: int = 0

property runtime: float

Seconds since the task started.

property cancellable: bool

True if the task may be cancelled; only logics are.

property next_warn_after: float | None

Runtime in seconds at which the next warning is due (runtime_warn, then each doubling); None if disabled.

property overdue: bool

True once the task has exceeded its runtime_warn threshold.

class lib.scheduler.Scheduler(smarthome)

Bases: Thread

static get_instance()

Returns the instance of the scheduler class, to be used to access the scheduler-api

Use it the following way to access the api:

from lib.scheduler import Scheduler

scheduler = Scheduler.get_instance()

# to access a method (eg. to trigger a logic):
scheduler.trigger(...)

Rückgabe:

scheduler instance

Rückgabetyp:

object or None

set_worker_warn_count(count)

get_worker_count()

Get number of worker threads initialized by scheduler

Rückgabe:

number of worker threads

get_idle_worker_count()

Get number of idle worker threads

Rückgabe:

number of worker threads

get_worker_names()

Get names on non-idle worker threads

Rückgabe:

list with names of worker threads

get_running_tasks()

Get the tasks currently executing on worker threads

Rückgabetyp:

list[RunningTask]

Rückgabe:

copies of the running tasks, in no particular order

get_task_stack(thread_ident)

Get the current call stack of a running task

Parameter:

thread_ident (int) – thread ident of the worker thread running the task

Rückgabetyp:

list[str] | None

Rückgabe:

stack as formatted by traceback.format_stack(), None if no task runs on that thread

cancel_task(thread_ident, task_id)

Request cancellation of a running logic by raising TaskCancelled in it

The exception arrives at the logic’s next bytecode boundary: immediately in a busy loop, but only after a blocking call (sleep, wait, lock, socket, subprocess) returns. A logic swallowing it (bare except:) keeps running; repeated requests raise it again.

Parameter:

• thread_ident (int) – thread ident of the worker thread running the task

• task_id (int) – task_id of the task run to cancel; a different run on that thread is not touched

Rückgabetyp:

Literal['requested', 'not_found', 'not_cancellable']

Rückgabe:

‚requested‘, ‚not_found‘ (no such task run) or ‚not_cancellable‘ (not a logic)

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

stop()

trigger(name, obj=None, by='Logic', source=None, value=None, dest=None, prio=3, dt=None, from_smartplugin=False)

triggers the execution of a logic optional at a certain datetime given with dt

Parameter:

• name

• obj

• by

• source

• value

• dest

• prio

• dt – a certain datetime

Rückgabe:

always None

remove(name, from_smartplugin=False)

Remove a scheduler entry with given name. If a call is made from a SmartPlugin with an instance configuration the instance name is added to the name to be able to distinguish scheduler entries from different instances

Parameter:

• name – scheduler entry name to remove

• from_smartplugin

check_caller(name, from_smartplugin=False)

Checks the calling stack if the calling function (one of get, change, remove, trigger) itself was called by a smartplugin instance. If there is an instance name of the calling smartplugin then the instance name of that calling smartplugin is appended to the name

Parameter:

• name – the name of a scheduler entry

• from_smartplugin

Rückgabe:

returns either the name or name combined with instance name

return_next(name, from_smartplugin=False)

add(name, obj, prio=3, cron=None, cycle=None, value=None, offset=None, next=None, from_smartplugin=False, items=None)

Adds an entry to the scheduler.

Parameter:

• name – Name of the scheduler

• obj – Method to call by the scheduler

• prio – a priority with default of 3 having 1 as most important and higher numbers less important

• cron – a crontab entry of type string or a list of entries

• cycle – a time given as integer in seconds or a string with a time given in seconds and a value after an equal sign or

• value – Value that an item should be set to or to be handed to a logic, otherwise: None

• offset – an optional offset for cycle. If not given, cycle start point will be varied between 10..15 seconds to prevent too many scheduler entries with the same starting times

• next

• from_smartplugin – Only to set to True, if called from the internal method in SmartPlugin class

• items – None or list of items to register for update_item calls (if cycle time is calculated from expression containing item(s))

update_item(item, caller=None, source=None, dest=None)

provide a mechanism to handle changes of cycle item references

get(name, from_smartplugin=False)

takes a given name for a scheduler and returns either the matching scheduler or None

change(name, from_smartplugin=False, **kwargs)

changes a scheduler entry for a given name to settings given in kwargs