qml.tape.QueuingContext

class QueuingContext[source]

Bases: abc.ABC

Abstract base class for classes that exposes a queue for objects.

This class provides a context manager that tracks queuable objects and queuing functions. Queuable objects are objects that queue themselves via QueuingContext.append(self), while queuing functions queue external objects.

Queuable objects make use of the following QueuingContext methods and properties:

  • recording: determine whether a queuing context is actively recording operations

  • append(): append an object to the active queuing context

  • remove(): remove an object from the queuing context. If the object is queued multiple times, only the first occurrence is removed.

  • update_info(): updates metadata attached to an object in the queue (not supported by all queuing contexts).

  • get_info(): retrieves metadata attached to an object in the queue (not supported by all queuing contexts).

Queuing context subclasses must define the following abstract methods:

  • _append(): define an action to perform when an object append request is made.

  • _remove(): define an action to perform when an object removal request is made.

In addition, the optional methods _update_info() and get_info may also be defined as required.

Example

To create a queuing context, simply subclass from QueuingContext and define the required methods:

>>> class MyQueue(QueuingContext):
...     def __init__(self):
...         self.queue = []
...     def _append(self, obj):
...         self.queue.append(obj)
...     def _remove(self, obj):
...         self.queue.remove(obj)

Once defined, it can be used as a queuing context to track queuable objects and queuing functions:

>>> with MyQueue() as q:
...     QueuingContext.append("object")
>>> print(q.queue)
['object']

Note that QueuingContext subclasses support nesting; objects are only queued to the first surrounding queuing context:

>>> with MyQueue() as q1:
...     with MyQueue() as q2:
...         QueuingContext.append("first object")
...     QueuingContext.append("second object")
...
>>> print(q1.queue)
['second object']
>>> print(q2.queue)
['first object']

Finally, queuing contexts themselves can be queuable objects:

>>> class QueuableQueue(QueuingContext):
...     def __init__(self):
...         self.queue = []
...         QueuingContext.append(self)
...     def _append(self, obj):
...         self.queue.append(obj)
...     def _remove(self, obj):
...         self.queue.remove(obj)

We can see that nested QueuableQueue objects are queued to their surrounding queuing context:

>>> with QueuableQueue() as q1:
...     with QueuableQueue() as q2:
...         QueuingContext.append("first object")
...     QueuingContext.append("second object")
>>> print(q1.queue)
[<__main__.QueuableQueue object at 0x7f94c432b6d0>, 'second object']
>>> print(q1.queue[0].queue)
['first object']

active_context()

Returns the currently active queuing context.

append(obj, **kwargs)

Append an object to the queue(s).

get_info(obj)

Retrieves information of an object in the active queue.

recording()

Whether a queuing context is active and recording operations

remove(obj)

Remove an object from the queue(s) if it is in the queue(s).

update_info(obj, **kwargs)

Updates information of an object in the active queue.

classmethod active_context()[source]

Returns the currently active queuing context.

classmethod append(obj, **kwargs)[source]

Append an object to the queue(s).

Parameters

obj – the object to be appended

classmethod get_info(obj)[source]

Retrieves information of an object in the active queue.

Parameters

obj – the object with metadata to be retrieved

Returns

object metadata

classmethod recording()[source]

Whether a queuing context is active and recording operations

classmethod remove(obj)[source]

Remove an object from the queue(s) if it is in the queue(s).

Parameters

obj – the object to be removed

classmethod update_info(obj, **kwargs)[source]

Updates information of an object in the active queue.

Parameters

obj – the object with metadata to be updated