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 :class:`~qm.QuatnumMachine.QuantumMachine`.
The following adds a job to the queue:


.. code-block:: python
	
    # 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:

.. code-block:: python

    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 :class:`~qm.QmPendingJob` object, so queries return such instances.

Important note: The queue is 1-based

.. code-block:: python

    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:

.. code-block:: python

    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.

.. code-block:: python

    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