[pve-devel] [PATCH qemu-server 1/3] qmp client: add $noerr argument

[Fiona Ebner]

Using the $noerr argument will allow callers to opt-in to handling
errors themselves.

Signed-off-by: Fiona Ebner <f.ebner at proxmox.com>
---
 src/PVE/QMPClient.pm          |  8 ++++---
 src/PVE/QemuServer/Monitor.pm | 40 ++++++++++++++++++++++++++++++++---
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/src/PVE/QMPClient.pm b/src/PVE/QMPClient.pm
index 87d61144..7b19be9d 100644
--- a/src/PVE/QMPClient.pm
+++ b/src/PVE/QMPClient.pm
@@ -86,7 +86,7 @@ sub queue_cmd {
 
 # execute a single command
 sub cmd {
-    my ($self, $vmid, $cmd, $timeout) = @_;
+    my ($self, $vmid, $cmd, $timeout, $noerr) = @_;
 
     my $result;
 
@@ -155,8 +155,10 @@ sub cmd {
 
     $self->queue_execute($timeout, 2);
 
-    die "VM $vmid qmp command '$cmd->{execute}' failed - $queue_info->{error}"
-        if defined($queue_info->{error});
+    if (defined($queue_info->{error})) {
+        die "VM $vmid qmp command '$cmd->{execute}' failed - $queue_info->{error}" if !$noerr;
+        $result = { error => $queue_info->{error} };
+    }
 
     return $result;
 }
diff --git a/src/PVE/QemuServer/Monitor.pm b/src/PVE/QemuServer/Monitor.pm
index 5956e1c4..062e71be 100644
--- a/src/PVE/QemuServer/Monitor.pm
+++ b/src/PVE/QemuServer/Monitor.pm
@@ -12,14 +12,48 @@ our @EXPORT_OK = qw(
     mon_cmd
 );
 
+=head3 qmp_cmd
+
+    my $cmd = { execute => $qmp_command_name, arguments => \%params };
+    my $result = qmp_cmd($vmid, $cmd);
+
+Execute the C<$qmp_command_name> with arguments C<%params> for VM C<$vmid>. Dies if the VM is not
+running or the monitor socket cannot be reached, even if the C<noerr> argument is used. Returns the
+structured result from the QMP side converted from JSON to structured Perl data. In case the
+C<noerr> argument is used and the QMP command failed or timed out, the result is a hash reference
+with an C<error> key containing the error message.
+
+Parameters:
+
+=over
+
+=item C<$vmid>: The ID of the virtual machine.
+
+=item C<$cmd>: Hash reference containing the QMP command name for the C<execute> key and additional
+arguments for the QMP command under the C<arguments> key. The following custom arguments are not
+part of the QMP schema and supported for all commands:
+
+=over
+
+=item C<timeout>: wait at most for this amount of time. If there was no actual error, the QMP/QGA
+command will still continue to be executed even after the timeout reached.
+
+=item C<noerr>: do not die when the command gets an error or the timeout is hit. The caller needs to
+handle the error that is returned as a structured result.
+
+=back
+
+=back
+
+=cut
 sub qmp_cmd {
     my ($vmid, $cmd) = @_;
 
     my $res;
 
-    my $timeout;
+    my ($noerr, $timeout);
     if ($cmd->{arguments}) {
-        $timeout = delete $cmd->{arguments}->{timeout};
+        ($noerr, $timeout) = delete($cmd->{arguments}->@{qw(noerr timeout)});
     }
 
     eval {
@@ -28,7 +62,7 @@ sub qmp_cmd {
         if (-e $sname) { # test if VM is reasonably new and supports qmp/qga
             my $qmpclient = PVE::QMPClient->new();
 
-            $res = $qmpclient->cmd($vmid, $cmd, $timeout);
+            $res = $qmpclient->cmd($vmid, $cmd, $timeout, $noerr);
         } else {
             die "unable to open monitor socket\n";
         }
-- 
2.47.2