10:57 a.m.
For change, pause, resume, complete, dismiss and finalize actions
corresponding job- and block-job commands are almost equal. The
difference is in find_block_job_locked() vs find_job_locked()
functions. What's different?
1. find_block_job_locked() do check, is found job a block-job. This OK
when moving to more generic API, no needs to document this change.
2. find_block_job_locked() reports DeviceNotActive on failure, when
find_job_locked() reports GenericError. So, lets document this
difference in deprecated.txt. Still, for dismiss and finalize errors
are not documented at all, so be silent in deprecated.txt as well.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov(a)yandex-team.ru>
---
Hi all!
That's a continuation of my "[RFC 00/15] block job API"[1], exactly, the
simplest part of it - deprecating block-job-* commands which simply
duplicate job-* ones.
Note that the old series was started with trying to introduce job-change
command as substitution to both block-job-change (which only can change
mirror copy-mode parameter), and block-job-set-speed. It was rather
complicated and controversial attempt, which latest implemenation was
"[PATCH v3 0/7] introduce job-change qmp command"[2].
In [2] Kevin noted, that we'd better follow existing blockdev-reopen
approach of changing options (i.e. specify all options) than introduce a
new one. But, on the other hand, now I'm afraid, that rewriting in
third tools simple call to (old good) block-job-set-speed into
job-change(_all_options_ + changed speed) is too much work just for
"having nice interface". And too much for the only two options we want
to change.
So, let's just start from something more obvious. Finally,
we can simple keep block-job-set-speed and block-job-change as is,
as they (unlike other block-job-* commands) are not duplicated by
similar job-* commands.
[1] https://patchew.org/QEMU/20240313150907.623462-1-vsementsov@yandex-team.ru/
[2] https://patchew.org/QEMU/20241002140616.561652-1-vsementsov@yandex-team.ru/
docs/about/deprecated.rst | 31 +++++++++++++++++++++++++++++++
qapi/block-core.json | 30 ++++++++++++++++++++++++++++++
2 files changed, 61 insertions(+)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index e2b4f077d4..eed3356359 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -148,6 +148,37 @@ options are removed in favor of using explicit ``blockdev-create``
and
``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
details.
+``block-job-pause`` (since 10.1)
+'''''''''''''''''''''''''''''''
+
+Use ``job-pause`` instead. The only difference is that ``job-pause``
+always reports GenericError on failure when ``block-job-pause`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-resume`` (since 10.1)
+''''''''''''''''''''''''''''''''
+
+Use ``job-resume`` instead. The only difference is that ``job-resume``
+always reports GenericError on failure when ``block-job-resume`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-complete`` (since 10.1)
+''''''''''''''''''''''''''''''''''
+
+Use ``job-complete`` instead. The only difference is that ``job-complete``
+always reports GenericError on failure when ``block-job-complete`` reports
+DeviceNotActive when block-job is not found.
+
+``block-job-dismiss`` (since 10.1)
+'''''''''''''''''''''''''''''''''
+
+Use ``job-dismiss`` instead.
+
+``block-job-finalize`` (since 10.1)
+''''''''''''''''''''''''''''''''''
+
+Use ``job-finalize`` instead.
+
``query-migrationthreads`` (since 9.2)
''''''''''''''''''''''''''''''''''''''
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b1937780e1..264be8413b 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2968,6 +2968,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-pause
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -2975,6 +2980,7 @@
# Since: 1.3
##
{ 'command': 'block-job-pause', 'data': { 'device':
'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -2992,6 +2998,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-resume
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -2999,6 +3010,7 @@
# Since: 1.3
##
{ 'command': 'block-job-resume', 'data': { 'device':
'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3023,6 +3035,11 @@
# the name of the parameter), but since QEMU 2.7 it can have other
# values.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-complete
+# instead.
+#
# Errors:
# - If no background operation is active on this device,
# DeviceNotActive
@@ -3030,6 +3047,7 @@
# Since: 1.3
##
{ 'command': 'block-job-complete', 'data': { 'device':
'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3047,9 +3065,15 @@
#
# @id: The job identifier.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-dismiss
+# instead.
+#
# Since: 2.12
##
{ 'command': 'block-job-dismiss', 'data': { 'id':
'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
@@ -3064,9 +3088,15 @@
#
# @id: The job identifier.
#
+# Features:
+#
+# @deprecated: This command is deprecated. Use @job-finalize
+# instead.
+#
# Since: 2.12
##
{ 'command': 'block-job-finalize', 'data': { 'id':
'str' },
+ 'features': ['deprecated'],
'allow-preconfig': true }
##
--
2.48.1