Jobs Queue

The queue system enables users to send multiple jobs to the orchestration platform, which are then run in turn. It provides tools to add and remove jobs from the queue as well as receive additional information such as the identity of the initiating user and the job start time.

Adding to queue

The queue is accessed by member functions of QuantumMachine. The following adds a job to the queue:

# Adding to the queue
qm.queue.add(program)  # adds at the end of the queue
qm.queue.add_to_start(program)  # adds at the start of the queue

Inspecting the queue

You can observe the queue and get the number of currently pending jobs as follows:

qm.queue.count  # number of items in the queue.
len(qm.queue) # same as count

The queue can be queried by either job_id, user_id or by position in queue. user_id given by the name passed to the QMApp. The queue is composed of instances of the QmPendingJob object, so queries return such instances.

Important note: The queue is 1-based

qm.queue.pending_jobs  # returns the list of jobs ids in the queue by the order they are in it (a list of QmPendingJob)
qm.queue.get_at(position)  # returns a QmPendingJob object
qm.queue[position] # the QmPendingJob at position
qm.queue.get(job_id) # returns a QmPendingJob object
qm.queue.get_by_user_id(user_id) # returns a QmPendingJob object

Interacting with a pending job object

A pending job object allows access to its run state and other information. This, for example allows to perform a blocking wait until the job completes:

pending_job = qm.queue.get_at(2)
pending_job.user_added  # user who executed
pending_job.position_in_queue() # return the current position in the queue
pending_job.time_added  # when the job was added to the queue
pending_job.wait_for_execution()  # waits until the job is executed (or aborted) and returns a QmJob.

Removing pending jobs from queue

Jobs can be removed from the queue by job_id, position or user_id. Note that at the moment, any user can remove any job from the queue. There is no facility to protect jobs from accidental removal. Also note that removing a job by position in queue can be unpredictable as the position of jobs change with time and so calling the remove by position function may remove a different job to that intended.

pending_job = qm.queue[2]
pending_job.cancel()  # remove from the queue
# Or
qm.queue.remove_by_id(job_id)  # removes by the job_id
qm.queue.remove_by_position(position)  # removes by the position in the queue. Might be dangerous because position can change during the request
qm.queue.remove_by_user_id(user_id)  # removes all jobs that belong to the user