Skip to content

Commit 78cd7f0

Browse files
author
Al Chu11
committed
tutorials: Add a flux job cancel tutorial
1 parent 7412532 commit 78cd7f0

File tree

4 files changed

+121
-0
lines changed

4 files changed

+121
-0
lines changed

‎auto_examples/auto_examples_jupyter.zip‎

0 Bytes
Binary file not shown.

‎auto_examples/auto_examples_python.zip‎

0 Bytes
Binary file not shown.

‎tutorials/commands/flux-job-cancel.rst‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
.. _flux-job-cancel:
2+
.. _flux-job-cancelall:
3+
4+
========================
5+
How to Cancel a Flux Job
6+
========================
7+
8+
Inevitably submitted jobs will have to be canceled for one reason or another. This tutorial
9+
will show you how.
10+
11+
----------------------
12+
Basic Job Cancellation
13+
----------------------
14+
15+
The basic way to cancel a job is through ``flux job cancel``. All you have to do is specify
16+
the jobid on the command line. Here is a simple example after submitting a job.
17+
18+
.. code-block:: console
19+
20+
$ flux mini submit sleep 100
21+
ƒh35Dh5qRyq
22+
23+
$ flux jobs ƒh35Dh5qRyq
24+
JOBID USER NAME ST NTASKS NNODES TIME INFO
25+
ƒh35Dh5qRyq achu sleep R 1 1 13.33s corona174
26+
27+
$ flux job cancel ƒh35Dh5qRyq
28+
29+
<snip wait a little bit>
30+
31+
$ flux jobs ƒh35Dh5qRyq
32+
JOBID USER NAME ST NTASKS NNODES TIME INFO
33+
ƒh35Dh5qRyq achu sleep CA 1 1 20.18s corona174
34+
35+
In the above example we submitted a simple job via ``flux mini submit`` that simply
36+
runs ``sleep``. Passing the resulting jobid to ``flux jobs`` shows that it is
37+
running (state is ``R``).
38+
39+
We cancel the job simply by passing the jobid to ``flux job cancel``. After waiting
40+
a little bit, we see that the job is now canceled in ``flux jobs`` (state is ``CA``).
41+
42+
Note that in this particular example we happened to know the jobid of our job. If you do
43+
not know the the jobid of your job, you can always use ``flux jobs`` to see a list of all
44+
your currently active jobs.
45+
46+
------------------------
47+
Cancelling a lot of jobs
48+
------------------------
49+
50+
The special ``flux job cancelall`` command allows you to cancel many jobs. Several options allow you to
51+
target a specific set of jobs.
52+
53+
To start off, lets create 100 jobs that will sleep infinitely. We will use the special ``--cc`` (carbon copy)
54+
option to ``flux mini submit`` that will submit 100 duplicate copies of the ``sleep`` job.
55+
56+
.. code-block:: console
57+
58+
$ flux mini submit --cc=1-100 sleep inf
59+
<snip - many job ids printed out>
60+
61+
$ flux jobs
62+
JOBID USER NAME ST NTASKS NNODES TIME INFO
63+
ƒjTWS5m3 achu sleep S 1 - -
64+
ƒjTWS5m4 achu sleep S 1 - -
65+
ƒjTWS5m5 achu sleep S 1 - -
66+
ƒjTWS5m6 achu sleep S 1 - -
67+
<snip - there are many jobs waiting to be run>
68+
ƒjTWS5m2 achu sleep R 1 1 8.858s corona212
69+
ƒjTWS5m1 achu sleep R 1 1 8.860s corona212
70+
ƒjTUx6Um achu sleep R 1 1 8.870s corona212
71+
ƒjTUx6Uk achu sleep R 1 1 8.870s corona212
72+
ƒjTUx6Uj achu sleep R 1 1 8.870s corona212
73+
ƒjTUx6Ui achu sleep R 1 1 8.871s corona212
74+
<snip - there are many jobs running>
75+
76+
As you can see, we have a lot of jobs waiting to run (state ``S``) and a lot of running jobs (state ``R``).
77+
78+
Lets first ``flux job cancelall`` without any options.
79+
80+
.. code-block:: console
81+
82+
$ flux job cancelall
83+
flux-job: Command matched 100 jobs (-f to confirm)
84+
85+
As you can see, ``flux job cancelall`` found all 100 jobs to cancel, but it hasn't canceled them yet. In order to go through
86+
with the cancellation you must specify the ``-f`` (or ``--force``) option.
87+
88+
.. code-block:: console
89+
90+
$ flux job cancelall -f
91+
flux-job: Canceled 100 jobs (0 errors)
92+
93+
$ flux jobs
94+
JOBID USER NAME ST NTASKS NNODES TIME INFO
95+
96+
As you can see all the jobs are now canceled after passing the ``-f`` option to ``flux job cancelall``. ``flux jobs``
97+
confirms this as no jobs are now listed.
98+
99+
``flux job cancellall`` has several options to filter the jobs to cancel. Perhaps the most commonly used
100+
option is the ``-S`` or ``--states`` option. The ``--states`` option specifies the state(s) of a job to cancel. The most
101+
common states to target are ``pending`` and ``running``. Lets resubmit our 100 jobs and see the result
102+
of trying to cancel ``pending`` vs ``running`` jobs.
103+
104+
.. code-block:: console
105+
106+
$ flux mini submit --cc=1-100 sleep inf
107+
<snip - many job ids printed out>
108+
109+
$ flux job cancelall --states=pending
110+
flux-job: Command matched 52 jobs (-f to confirm)
111+
112+
$ flux job cancelall --states=running
113+
flux-job: Command matched 48 jobs (-f to confirm)
114+
115+
As you can see ``flux job cancelall --states=pending`` would target the 52 pending jobs for cancellation and
116+
``flux job cancelall --states=running`` would target the current 48 running jobs for cancellation.
117+
118+
And that's it! If you have any questions, please
119+
`let us know <https://github.com/flux-framework/flux-docs/issues>`_.

‎tutorials/commands/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Welcome to the Command Tutorials! These tutorials should help you to map specifi
77
with your use case, and then see detailed usage.
88

99
- ``flux mini submit/flux mini run`` (:ref:`flux-mini-submit`): "Submit a job in a Flux instance"
10+
- ``flux job cancel/flux job cancelall`` (:ref:`flux-job-cancel`): "Cancel a job you submitted"
1011
- ``flux proxy`` (:ref:`ssh-across-clusters`): "Send commands to a Flux instance across clusters using ssh"
1112

1213
This section is currently 🚧️ under construction 🚧️, so please come back later to see more command tutorials!
@@ -17,4 +18,5 @@ This section is currently 🚧️ under construction 🚧️, so please come bac
1718
:caption: Command Tutorials
1819

1920
flux-mini-submit
21+
flux-job-cancel
2022
ssh-across-clusters

0 commit comments

Comments
 (0)