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.

__init__(func, name, args, kwargs)

Initialize self. See help(type(self)) for accurate signature.

__dict__ = mappingproxy({'__module__': 'fsleyes_props.callqueue', '__doc__': 'A little class which is used to represent function calls that are\n on the queue.\n ', '__init__': <function Call.__init__>, '__dict__': <attribute '__dict__' of 'Call' objects>, '__weakref__': <attribute '__weakref__' of 'Call' objects>})

__module__ = 'fsleyes_props.callqueue'

__weakref__

list of weak references to the object (if defined)

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.

__init__(skipDuplicates=False)

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.

_CallQueue__call()

Call all of the functions which are currently enqueued.

This method is not re-entrant - if a call to one of the functions in the queue triggers another call to this method, this second call will return immediately without doing anything.

_CallQueue__debug(call, prefix, postfix=None)

Prints a standardised log message.

_CallQueue__getCallbackDetails(cb)

Returns the function name and module name of the given function reference. Used purely for debug log statements.

_CallQueue__pop()

Pops the next function from the queue and returns the Call instance which encapsulates it.

_CallQueue__push(call)

Enqueues the given Call instance.

If the queue has been held (see hold()), the call is stored, and False is returned.

If True was passed in for the skipDuplicates parameter during initialisation, and the function is already enqueued, it is not added to the queue, and this method returns False.

Otherwise, this method returnes True.

__dict__ = mappingproxy({'__module__': 'fsleyes_props.callqueue', '__doc__': 'A queue of functions to be called. Functions can be enqueued via\n the :meth:`call` or :meth:`callAll` methods.\n ', '__init__': <function CallQueue.__init__>, 'dequeue': <fsl.utils.idle.MutexFactory object>, 'call': <function CallQueue.call>, 'callAll': <function CallQueue.callAll>, 'hold': <fsl.utils.idle.MutexFactory object>, 'release': <fsl.utils.idle.MutexFactory object>, 'clearHeld': <fsl.utils.idle.MutexFactory object>, '_CallQueue__call': <function CallQueue.__call>, '_CallQueue__push': <fsl.utils.idle.MutexFactory object>, '_CallQueue__pop': <fsl.utils.idle.MutexFactory object>, '_CallQueue__debug': <function CallQueue.__debug>, '_CallQueue__getCallbackDetails': <function CallQueue.__getCallbackDetails>, '__dict__': <attribute '__dict__' of 'CallQueue' objects>, '__weakref__': <attribute '__weakref__' of 'CallQueue' objects>})

__module__ = 'fsleyes_props.callqueue'

__weakref__

list of weak references to the object (if defined)