Timer — kaa.base v0.6.0 documentation

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »

# Timer

## The timed decorator

FIXME: this section is not yet written

`kaa.` `timed`(interval, timer=None, policy=POLICY_MANY)

  Decorator to call the decorated function in a Timer. When calling the function, a timer will be started with the given interval calling that function. The decorated function will be called from the main thread.

  The timer parameter optionally specifies which timer class should be used to wrap the function. kaa.Timer (default) or kaa.WeakTimer will repeatedly invoke the decorated function until it returns False. kaa.OneShotTimer or kaa.WeakOneShotTimer will invoke the function once, delaying it by the specified interval. (In this case the return value of the decorated function is irrelevant.)

  The policy parameter controls how multiple invocations of the decorated function should be handled. By default (POLICY_MANY), each invocation of the function will create a new timer, each firing at the specified interval. If policy is POLICY_ONCE, subsequent invocations are ignored while the first timer is still active. If the policy is POLICY_RESTART, subsequent invocations will restart the first timer.

  Note that in the case of POLICY_ONCE or POLICY_RESTART, if the timer is currently running, any arguments passed to the decorated function on subsequent calls will be discarded.

## Timer Callbacks

FIXME: this section is not yet written

class `kaa.` `Timer`(callback, *args, **kwargs)

  Invokes the supplied callback after the supplied interval (passed to `start()`) elapses. The Timer is created stopped.

  When the timer interval elapses, we say that the timer is “fired” or “triggered,” at which time the given callback is invoked.

  If the callback returns False, then the timer is automatically stopped. If it returns any other value (including None), the timer will continue to fire.

  Parameters: | callback – the callable to be invoked args – the arguments to be passed to the callable when it’s invoked kwargs – the keyword arguments to be passed to the callable when it’s invoked

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.Timer`

  Methods

  `start()` | Start the timer, invoking the callback every interval seconds.
  `stop()` | Stop a running timer.

  Properties

  `interval` | read-only | Timer interval when the timer is running, None if not. The interval cannot be changed once the timer is started, and it is set via the `start()` method.

  Signals

  This class has no signals.

  #### Methods

  `start`(interval)

    Start the timer, invoking the callback every interval seconds.

    If the timer is already running, it is stopped and restarted with the given interval. The timer’s precision is at the mercy of other tasks running in the main loop. For example, if another task (a different timer, or I/O callback) blocks the mainloop for longer than the given timer interval, the callback will be invoked late.

    Parameters: | interval – interval between invocations of the callback, in seconds

  `stop`()

    Stop a running timer.

    This method can be called safely even if the timer is already stopped.

  #### Properties

  `interval`
    Timer interval when the timer is running, None if not. The interval cannot be changed once the timer is started, and it is set via the `start()` method.

class `kaa.` `WeakTimer`(callback, *args, **kwargs)

  Weak variant of the Timer class.

  All references to the callback and supplied args/kwargs are weak references. When any of the underlying objects are deleted, the WeakTimer is automatically stopped.

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.WeakCallback`
  └─ `kaa.Timer`
  └─ `kaa.WeakNotifierCallback`
  └─ `kaa.WeakTimer`

class `kaa.` `OneShotTimer`(callback, *args, **kwargs)

  A Timer that gets triggered exactly once when it is started. Useful for deferred one-off tasks.

  Gotcha: it is possible to restart a OneShotTimer from inside the callback it invokes, however be careful not to return False in this case, otherwise the freshly started OneShotTimer will be implicitly stopped before it gets a chance to fire.

  Parameters: | callback – the callable to be invoked args – the arguments to be passed to the callable when it’s invoked kwargs – the keyword arguments to be passed to the callable when it’s invoked

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.Timer`
  └─ `kaa.OneShotTimer`

class `kaa.` `WeakOneShotTimer`(callback, *args, **kwargs)

  Weak variant of the OneshotTimer class.

  All references to the callback and supplied args/kwargs are weak references. When any of the underlying objects are deleted, the WeakTimer is automatically stopped.

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.Callback`
  └─ `kaa.Timer`
  └─ `kaa.NotifierCallback`
  └─ `kaa.WeakCallback`
  └─ `kaa.OneShotTimer`
  └─ `kaa.WeakNotifierCallback`
  └─ `kaa.WeakOneShotTimer`

class `kaa.` `OneShotAtTimer`(callback, *args, **kwargs)

  A timer that is triggered at a specific time of day. Once the timer fires it is stopped.

  Parameters: | callback – the callable to be invoked args – the arguments to be passed to the callable when it’s invoked kwargs – the keyword arguments to be passed to the callable when it’s invoked

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.Timer`
  └─ `kaa.OneShotTimer`
  └─ `kaa.OneShotAtTimer`

  Methods

  `start()` | Starts the timer, causing it to be fired at the specified time.

  #### Methods

  `start`(hour=range(24), min=range(60), sec=0)

    Starts the timer, causing it to be fired at the specified time.

    By default, the timer will fire every minute at 0 seconds. The timer has second precision.

    Parameters: | hour (int or list of ints) – the hour number (0-23) or list of hours min (int or list of ints) – the minute number (0-59) or list of minutes sec (int or list of ints) – the second number (0-59) or list of seconds

class `kaa.` `AtTimer`(callback, *args, **kwargs)

  A timer that is triggered at a specific time or times of day.

  Parameters: | callback – the callable to be invoked args – the arguments to be passed to the callable when it’s invoked kwargs – the keyword arguments to be passed to the callable when it’s invoked

  #### Synopsis

  Class Hierarchy

  `kaa.Callback`
  └─ `kaa.NotifierCallback`
  └─ `kaa.Timer`
  └─ `kaa.OneShotTimer`
  └─ `kaa.OneShotAtTimer`
  └─ `kaa.AtTimer`

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »