..
 # Copyright (c) 2026, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

###################
Using the Scheduler
###################

************
Introduction
************

The scheduler is the Fastpath service that manages access to SUT classes and
dispatches queued work onto concrete SUTs as they become available. It supports
two main workflows:

* **Plan execution**: submit a plan that targets a SUT class and let the
  scheduler split and run it across all available SUTs.
* **Manual leasing**: acquire a SUT from a SUT class for interactive use, then
  release it when finished.

This guide walks through setting up a small demo scheduler instance, saving the
scheduler URL and user token in Fastpath preferences, and then using the
scheduler CLI verbs to submit and manage plans and leases.

.. note::

   For low-level integration details and the REST interface itself, see
   :doc:`../developer-guide/scheduler_api`.


**********************
Start a Demo Scheduler
**********************

For a simple demo, use the built-in ``static`` SUT provider. Create a file
called ``sutclasses.yaml``:

.. code-block:: yaml

  - sutclass: demo
    type: static
    params:
      suts:
        - name: demo-01
          connection:
            method: SSH
            params:
              host: demo-01
              user: fpuser
              keyfile: /path/to/id_ed25519
        - name: demo-02
          connection:
            method: SSH
            params:
              host: demo-02
              user: fpuser
              keyfile: /path/to/id_ed25519

This defines a SUT class called ``demo`` containing two static SUTs.

Start the scheduler:

.. code-block:: shell

  fastpath sched run \
    --host 127.0.0.1 \
    --port 5000 \
    --database sqlite:///scheduler.db \
    --storage ./sched_storage \
    --sutclasses ./sutclasses.yaml

If you want scheduled plans to automatically publish into a resultstore, also
provide ``--resultstore``:

.. code-block:: shell

  fastpath sched run \
    --host 127.0.0.1 \
    --port 5000 \
    --database sqlite:///scheduler.db \
    --storage ./sched_storage \
    --sutclasses ./sutclasses.yaml \
    --resultstore sqlite:///scheduler-results.db

On first start the scheduler creates a default admin user and prints its token.
The admin user has all capabilities, including ``admin``:

.. code-block:: text

  ****
  Created default admin user 'admin' with token: <token>
  ****

Keep that token. It is needed to create additional scheduler users.

********************************
Save the Scheduler URL and Token
********************************

The scheduler CLI verbs take ``--url`` and ``--token`` options, but it is much
more convenient to store them as Fastpath preferences:

.. code-block:: shell

  fastpath preference set --category sched --name url http://127.0.0.1:5000
  fastpath preference set --category sched --name token <admin-token>

Now scheduler commands can be run without repeating either argument; if --url or
--token is omitted, they default to the values saved as preferences. For
example:

.. code-block:: shell

  fastpath sched sutclass-list

You can inspect the saved values with:

.. code-block:: shell

  fastpath preference get --category sched --name url
  fastpath preference get --category sched --name token

**********************
Create Scheduler Users
**********************

Create users with the ``sched user-create`` verb. Capabilities are passed as a
comma-separated list of lower-case names.

For example, create a user that can execute plans and query scheduler state:

.. code-block:: shell

  fastpath sched user-create alice --capabilities exec,query

Or create a user that can manually lease SUTs and query scheduler state:

.. code-block:: shell

  fastpath sched user-create bob --capabilities lease,query

Each command prints the created user's token. If you want to work as that user,
update the saved ``sched.token`` preference to the new token (or pass it with
--token).

***************************
Inspect the Scheduler State
***************************

List known SUT classes:

.. code-block:: shell

  fastpath sched sutclass-list

This shows the SUT class id, name, whether it is enabled, current usage, and
creation time.

To report usage over a specific time window, provide ``--from`` and/or
``--to``:

.. code-block:: shell

  fastpath sched sutclass-list --from 2026-03-01
  fastpath sched sutclass-list --from 2026-03-01 --to 2026-04-01

*************
Submit a Plan
*************

Plans submitted to the scheduler must target a SUT class rather than a specific
SUT. For example:

.. code-block:: yaml

  sut:
    sutclass: demo
  swprofiles:
    - name: baseline
      kernel: /path/to/Image
      modules: /path/to/modules.tar.xz
  benchmarks:
    - include: speedometer/v2.1.yaml
    - include: mmtests/kernbench.yaml
  defaults:
    benchmark:
      warmups: 1
      repeats: 3
      sessions: 3
      timeout: 1h

Submit it to the scheduler:

.. code-block:: shell

  fastpath sched plan-exec demo-plan.yaml

Optionally set a priority:

.. code-block:: shell

  fastpath sched plan-exec --priority 8 demo-plan.yaml

If the scheduler was started with ``--resultstore``, scheduled plan results are
published there by default. To queue a plan without publishing its results:

.. code-block:: shell

  fastpath sched plan-exec --no-publish demo-plan.yaml

If the plan references local files (e.g. kernel or modules), the scheduler
client automatically uploads them along with the plan payload.

**********************
Track and Manage Plans
**********************

List all plans:

.. code-block:: shell

  fastpath sched plan-list --all-users

Inspect specific plan by id:

.. code-block:: shell

  fastpath sched plan-list 12

The plan listing shows:

* the owning user
* the target SUT class
* plan priority
* progress as ``completed_jobs/total_jobs``
* plan status
* queued, started, and completed timestamps

Filter plan listings:

.. code-block:: shell

  fastpath sched plan-list --states running
  fastpath sched plan-list --users alice
  fastpath sched plan-list --all-users --all-states

By default, ``plan-list`` filters to the authenticated user and to plans in the
``queued`` or ``running`` states. Use ``--all-users`` and ``--all-states`` to
remove those default filters.

Update the priority of a queued or active plan:

.. code-block:: shell

  fastpath sched plan-update 12 --priority 3

Cancel a plan:

.. code-block:: shell

  fastpath sched plan-cancel 12

Cancellation is best-effort. Queued child jobs are cancelled immediately.
Already-running child jobs are allowed to finish naturally.

***************
Acquire a Lease
***************

To request a manual lease on a SUT from a SUT class:

.. code-block:: shell

  fastpath sched lease-acquire demo

To wait until the lease becomes active and a concrete SUT has been assigned:

.. code-block:: shell

  fastpath sched lease-acquire demo --wait

The command prints the lease details, including the assigned SUT once it is
available.

*************
Manage Leases
*************

List all leases:

.. code-block:: shell

  fastpath sched lease-list --all-users

Inspect a specific lease by id:

.. code-block:: shell

  fastpath sched lease-list 7

Filter lease listings:

.. code-block:: shell

  fastpath sched lease-list --states acquired
  fastpath sched lease-list --users bob
  fastpath sched lease-list --all-users --all-states

By default, ``lease-list`` filters to the authenticated user and to leases in
the ``queued`` or ``acquired`` states. Use ``--all-users`` and
``--all-states`` to remove those default filters.

Release a lease when finished:

.. code-block:: shell

  fastpath sched lease-release 7