# evennia.scripts.tickerhandler

TickerHandler

This implements an efficient Ticker which uses a subscription model to ‘tick’ subscribed objects at regular intervals.

The ticker mechanism is used by importing and accessing the instantiated TICKER_HANDLER instance in this module. This instance is run by the server; it will save its status across server reloads and be started automaticall on boot.

Example:

    from evennia.scripts.tickerhandler import TICKER_HANDLER

    # call tick myobj.at_tick(*args, **kwargs) every 15 seconds
    TICKER_HANDLER.add(15, myobj.at_tick, *args, **kwargs)

You supply the interval to tick and a callable to call regularly with any extra args/kwargs. The callable should either be a stand-alone function in a module or the method on a typeclassed entity (that is, on an object that can be safely and stably returned from the database). Functions that are dynamically created or sits on in-memory objects cannot be used by the tickerhandler (there is no way to reference them safely across reboots and saves).

The handler will transparently set up and add new timers behind the scenes to tick at given intervals, using a TickerPool - all callables with the same interval will share the interval ticker.

To remove:

    TICKER_HANDLER.remove(15, myobj.at_tick)

Both interval and callable must be given since a single object can be subscribed to many different tickers at the same time. You can also supply idstring as an identifying string if you ever want to tick the callable at the same interval but with different arguments (args/kwargs are not used for identifying the ticker). There is also persistent=False if you don’t want to make a ticker that don’t survive a reload. If either or both idstring or persistent has been changed from their defaults, they must be supplied to the TICKER_HANDLER.remove call to properly identify the ticker to remove.

The TickerHandler’s functionality can be overloaded by modifying the Ticker class and then changing TickerPool and TickerHandler to use the custom classes

    class MyTicker(Ticker):
        # [doing custom stuff]

    class MyTickerPool(TickerPool):
        ticker_class = MyTicker
    class MyTickerHandler(TickerHandler):
        ticker_pool_class = MyTickerPool

If one wants to duplicate TICKER_HANDLER’s auto-saving feature in a custom handler one can make a custom AT_STARTSTOP_MODULE entry to call the handler’s save() and restore() methods when the server reboots.

class `evennia.scripts.tickerhandler.``Ticker`(interval)

  Bases: `object`

  Represents a repeatedly running task that calls hooks repeatedly. Overload _callback to change the way it operates.

  `__init__`(interval)

    Set up the ticker

    Parameters

      interval (int) – The stepping interval.

  `validate`(start_delay=None)

    Start/stop the task depending on how many subscribers we have using it.

    Parameters

      start_delay (int) – Time to way before starting.

  `add`(store_key, *args, **kwargs)

    Sign up a subscriber to this ticker. :param store_key: Unique storage hash for this ticker subscription. :type store_key: str :param args: Arguments to call the hook method with. :type args: any, optional

    Keyword Arguments

      _start_delay (int) – If set, this will be used to delay the start of the trigger instead of interval.

  `remove`(store_key)

    Unsubscribe object from this ticker

    Parameters

      store_key (str) – Unique store key.

  `stop`()

    Kill the Task, regardless of subscriptions.

class `evennia.scripts.tickerhandler.``TickerPool`

  Bases: `object`

  This maintains a pool of evennia.scripts.scripts.ExtendedLoopingCall tasks for calling subscribed objects at given times.

  `ticker_class`

    alias of `Ticker`

  `__init__`()

    Initialize the pool.

  `add`(store_key, *args, **kwargs)

    Add new ticker subscriber.

    Parameters

      - store_key (str) – Unique storage hash.

      - args (any, optional) – Arguments to send to the hook method.

  `remove`(store_key)

    Remove subscription from pool.

    Parameters

      store_key (str) – Unique storage hash to remove

  `stop`(interval=None)

    Stop all scripts in pool. This is done at server reload since restoring the pool will automatically re-populate the pool.

    Parameters

      interval (int, optional) – Only stop tickers with this interval.

class `evennia.scripts.tickerhandler.``TickerHandler`(save_name='ticker_storage')

  Bases: `object`

  The Tickerhandler maintains a pool of tasks for subscribing objects to various tick rates. The pool maintains creation instructions and and re-applies them at a server restart.

  `ticker_pool_class`

    alias of `TickerPool`

  `__init__`(save_name='ticker_storage')

    Initialize handler

    save_name (str, optional): The name of the ServerConfig

      instance to store the handler state persistently.

  `save`()

    Save ticker_storage as a serialized string into a temporary ServerConf field. Whereas saving is done on the fly, if called by server when it shuts down, the current timer of each ticker will be saved so it can start over from that point.

  `restore`(server_reload=True)

    Restore ticker_storage from database and re-initialize the handler from storage. This is triggered by the server at restart.

    Parameters

      server_reload (bool, optional) – If this is False, it means the server went through a cold reboot and all non-persistent tickers must be killed.

  `add`(interval=60, callback=None, idstring='', persistent=True, *args, **kwargs)

    Add subscription to tickerhandler

    Parameters

      - interval (int, optional) – Interval in seconds between calling callable(*args, **kwargs)

      - callable (callable function or method, optional) – This should either be a stand-alone function or a method on a typeclassed entity (that is, one that can be saved to the database).

      - idstring (str, optional) – Identifier for separating this ticker-subscription from others with the same interval. Allows for managing multiple calls with the same time interval and callback.

      - persistent (bool, optional) – A ticker will always survive a server reload. If this is unset, the ticker will be deleted by a server shutdown.

      - args (optional) – These will be passed into the callback every time it is called. This must be data possible to pickle!

      - kwargs (optional) – These will be passed into the callback every time it is called. This must be data possible to pickle!

    Returns

      store_key (tuple) –

      The immutable store-key for this ticker. This can

        be stored and passed into .remove(store_key=store_key) later to easily stop this ticker later.

    Notes

    The callback will be identified by type and stored either as as combination of serialized database object + methodname or as a python-path to the module + funcname. These strings will be combined iwth interval and idstring to define a unique storage key for saving. These must thus all be supplied when wanting to modify/remove the ticker later.

  `remove`(interval=60, callback=None, idstring='', persistent=True, store_key=None)

    Remove ticker subscription from handler.

    Parameters

      - interval (int, optional) – Interval of ticker to remove.

      - callback (callable function or method) – Either a function or the method of a typeclassed object.

      - idstring (str, optional) – Identifier id of ticker to remove.

      - persistent (bool, optional) – Whether this ticker is persistent or not.

      - store_key (str, optional) – If given, all other kwargs are ignored and only this is used to identify the ticker.

    Raises

      KeyError – If no matching ticker was found to remove.

    Notes

    The store-key is normally built from the interval/callback/idstring/persistent values; but if the store_key is explicitly given, this is used instead.

  `clear`(interval=None)

    Stop/remove tickers from handler.

    Parameters

      interval (int) – Only stop tickers with this interval.

    Notes

    This is the only supported way to kill tickers related to non-db objects.

  `all`(interval=None)

    Get all subscriptions.

    Parameters

      interval (int) – Limit match to tickers with this interval.

    Returns

      tickers (list) –

      If interval was given, this is a list of

        tickers using that interval.

      tickerpool_layout (dict): If interval was not given,

        this is a dict {interval1: [ticker1, ticker2, …], …}

  `all_display`()

    Get all tickers on an easily displayable form.

    Returns

      tickers (dict) – A list of all storekeys