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, optional) – 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

*args – Will be passed into the callback every time it’s called. This must be data possible to pickle.

Keyword Arguments

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

• callable (callable function or method) – 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) – 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) – A ticker will always survive a server reload. If this is unset, the ticker will be deleted by a server shutdown.

• Will be passed into the callback every time it is called. (**kwargs) – 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.

Keyword Arguments

• interval (int) – Interval of ticker to remove.

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

• idstring (str) – Identifier id of ticker to remove.

• persistent (bool) – Whether this ticker is persistent or not.

• store_key (str) – 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, optional) – 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 ticker subscriptions.

Parameters

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

Returns

list or dict – If interval was given, this is a list of tickers using that interval. 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