[PATCH qemu-server v2 1/3] blockdev: commit: improve comment about completion mode

[Fiona Ebner <f.ebner@proxmox.com>]

For reference, see the QMP docs [0][1].

[0]: https://qemu.readthedocs.io/en/master/interop/qemu-qmp-ref.html#command-QMP-block-core.block-commit
[1]: https://qemu.readthedocs.io/en/master/interop/qemu-qmp-ref.html#command-QMP-job.job-complete

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 src/PVE/QemuServer/Blockdev.pm | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/PVE/QemuServer/Blockdev.pm b/src/PVE/QemuServer/Blockdev.pm
index af7e769b..8eb01b45 100644
--- a/src/PVE/QemuServer/Blockdev.pm
+++ b/src/PVE/QemuServer/Blockdev.pm
@@ -1074,7 +1074,15 @@ sub blockdev_commit {
         mon_cmd($vmid, "block-commit", %$opts);
         $jobs->{$job_id} = {};
 
-        # if we commit the current, the blockjob need to be in 'complete' mode
+        # If the 'current' state is committed to its backing snapshot, the job will not complete
+        # automatically, because there is a writer, i.e. the guest. It is necessary to use the
+        # 'complete' completion mode, so that the 'current' block node is replaced with the backing
+        # node upon completion. Like that, IO after the commit operation will already land in the
+        # backing node, which will be renamed since it will be the new top of the chain (done by the
+        # caller).
+        #
+        # For other snapshots in the chain, it can be assumed that they have no writer, so
+        # 'block-commit' will complete automatically.
         my $complete = $src_snap && $src_snap ne 'current' ? 'auto' : 'complete';
 
         eval {
-- 
2.47.3