Utility Functions

Additional functionality used within the Django Message Broker:

IntegerSequence - Iterator returning the next integer when accessed.
WeakPeriodicCallback - Modifies Tornado Periodic Callback with weak method references.
MethodProxy - Creates a register of weak references to methods.
WaitFor - Asyncio method to wait upon multiple coroutines or events.
MethodRegistry - Implements a decorator in a class to auto-create a registor of methods.

class django_message_broker.server.utils.IntegerSequence

Generates iterators of integer sequences.

new_iterator(start: int = 0) → Iterator[int]

Returns an iterator which generates the next integer in a sequence when called.

Parameters: start (int, optional) – Starting number of the sequence. Defaults to 0.
Yields: Iterator[int] – Iterator generating the next integer in a sequence.

class django_message_broker.server.utils.WeakPeriodicCallback(callback: Callable[[], Optional[Awaitable]], *args, **kwargs)

Implementation of Tornado PeriodCallback establishing a weak reference to the callable function.

A weak reference is required when the periodic callback is established in the initialization of a class to a callback method within the same class. In this situation the periodic callback holds a reference to an object within the class and the class can neither be deleted or garbage collected. This can lead to a memory leak. Establishing a weak link between the periodic callback and the callback method allows the callback to be removed from the event loop and the class deleted.

async _run() → None: Method called after the time that future is scheduled to run.

class django_message_broker.server.utils.MethodProxy

Creates a registry to proxy strong function references with weak ones.

classmethod register(callback: Callable) → Callable

Registers a callback in a registry of callable methods and returns a callback with a weakref to the original callback method.

Parameters: callback (Callable) – Original callback method.
Raises: ReferenceError – If the referenced callable has already been garbage the terminates future and propagates into enclosing waiting code.
Returns: Weakref callable to the original callback method.
Return type: Callable

classmethod unregister(callback: Callable) → None

Removes a callable method from the registry.

Parameters: callback (Callable) – Callable method to unregister

class django_message_broker.server.utils.WaitFor(events: List[asyncio.locks.Event])

Waits for a combination of events to occur before continuing code execution.

The code creates weak referenced callbacks which are triggered when an event in the list is set. The class exposes two asyncio methods:

one_event() - Which is triggered when any one of the events is set.
all_events() - Which is triggered when all the events are set.

_callback(task: _asyncio.Task) → None

Callback when an event is set. The callback is proxied so that the method reference is weak, enabling this class to be garbage collected before the task is complete.

Parameters: task (_type_) – Asyncio callbacks are passed with the task as argument.

async all_events() → None: Waits until all events are set.

async one_event() → None: Waits until any one event is set.

__del__() → None: Remove any outstanding tasks from the event loop.

class django_message_broker.server.utils.MethodRegistry

Meta class plug-in adding a dictionary of callable methods indexed by command name.

The class exposes a decorator that registers the method in a dictionary indexed by a named command (as byte string). The dictionary of callable methods is created when the class is imported; however, methods can only be bound to an instance of the class when the class is instantiated.

When an instance of the class is instantiated then a copy of the dictionary containing bound callable methods can be created by calling the get_bound_callables method passing the instance of the class as a parameter.

Example usage:

class MathsByName:
    # Create a registry of math functions
    class MathFunctions(MethodRegistry):
        pass

    def __init__(self):
        # Bind methods to instance
        self.maths = MathsByName.MathFunctions.get_bound_callables(self)

    @MathFunctions.register(command=b"plusOne")
    def f1(self, a):
        return a + 1

    @MathFunctions.register(command=b"sumTwo")
    def f2(self, a, b):
        return a + b

myMaths = MathsByName()
plus_one = myMaths.maths[b"plusOne"](1)  # result = 2
sum_two = myMaths.maths[b"sumTwo"](1, 2)  # result = 3

classmethod register(command: Optional[bytes] = None) → Callable

Decorator to register a named function in the dictionary of callables.

Parameters

command (bytes, optional) – Name of the command.

Raises

Exception – If no command is given.
Exception – If the command has already been defined.

classmethod get_bound_callables(self) → Dict[bytes, Callable]

Given an instance of the class, returns a dictionary of named methods.

Returns: Dictionary of callable methods.
Return type: Dict[bytes, Callable]