fsleyes_props.callqueue

This module provides the CallQueue class, which is used by PropertyValue instances to enqueue and execute property listener callback functions.

class fsleyes_props.callqueue.Call(func, name, args, kwargs)

Bases: object

A little class which is used to represent function calls that are on the queue.

class fsleyes_props.callqueue.CallQueue(skipDuplicates=False)

Bases: object

A queue of functions to be called. Functions can be enqueued via the call() or callAll() methods.

Create a CallQueue instance.

If skipDuplicates is True, a function which is already on the queue will be silently dropped if an attempt is made to add it again.

Note

The skipDuplicates test is based solely on the name of the function. This means that the CallQueue does not support enqueueing the same function with different arguments.

Testing for function and argument equality is a difficult task:

• I can’t take the hash of the arguments, as I can’t assume that they are hashable (e.g. numpy arrays).

• I can’t test for identity, as things which have the same value may not have the same id (e.g. strings).

• I can’t test argument equality, because in some cases the argument may be a mutable type (e.g. a list), and its value may have changed between the time the function was queued, and the time it is called. And the arguments might be big (again, numpy arrays), so an equality test could be expensive.

So this is quite a pickle. Something to come back to if things are breaking because of it.

Holding the queue

The hold() method temporarily stops the CallQueue from queueing and executing functions. Any functions which are enqueued while the queue is held are kept in a separate queue. The queue is released via the release() method, after which any held functions may be accessed via the clearHeld() method (which also clears the internal queue of held functions). Once the queue has been released, these held functions can be re-queued as normal via the call() or callAll() methods.

dequeue(name)

If the specified function is on the queue, it is (effectively) dequeued, and not executed.

If skipDuplicates is False, and more than one function of the same name is enqueued, they are all dequeued.

call(func, name, *args, **kwargs)

Enqueues the given function, and calls all functions in the queue

(unless the call to this method was as a result another function being called from the queue).

callAll(funcs)

Enqueues all of the given functions, and calls all functions in the queue.

(unless the call to this method was as a result another function being called from the queue).

Assumes that the given funcs parameter is a list of (function, name, args, kwargs) tuples.

hold()

Holds the queue. For every call to hold, the release() method must be called once before the queue will be truly released.

release()

Releases the queue.

clearHeld()

Clears and returns the list of held functions.