[libvirt] [PATCH 1/3] command: introduce virPidWait, virPidAbort

[Eric Blake]

On 07/14/2011 11:34 AM, Matthias Bolte wrote:
> 2011/7/12 Eric Blake <eblake at redhat.com>:
>> When using virCommandRunAsync and saving the pid for later, it
>> is useful to be able to reap that pid in the same way that it
>> would have been auto-reaped by virCommand if we had passed
>> NULL for the pid argument in the first place.
>>
> 
> ACK.

I'm pushing with this squashed in, as well as patch 2 and 3 as-is.  The
suggestion for avoiding the doc duplication between .c and .h will be
addressed as an upcoming patch 4/3 (unpushed until it gets reviewed).

diff --git i/src/util/command.c w/src/util/command.c
index bba82b0..e2ece78 100644
--- i/src/util/command.c
+++ w/src/util/command.c
@@ -1384,8 +1384,8 @@ virCommandToString(virCommandPtr cmd)

 /*
  * Translate an exit status into a malloc'd string.  Generic helper
- * for virCommandRun and virCommandWait status argument, as well as
- * raw waitpid and older virRun status.
+ * for virCommandRun, virCommandWait, and virPidWait status argument,
+ * as well as raw waitpid and older virRun status.
  */
 char *
 virCommandTranslateStatus(int status)
@@ -1807,6 +1807,17 @@ virCommandHook(void *data)
  * Run the command asynchronously
  * Returns -1 on any error executing the
  * command. Returns 0 if the command executed.
+ *
+ * There are two approaches to child process cleanup.
+ * 1. Use auto-cleanup, by passing NULL for pid.  The child will be
+ * auto-reaped by virCommandFree, unless you reap it earlier via
+ * virCommandWait or virCommandAbort.  Good for where cmd is in
+ * scope for the duration of the child process.
+ * 2. Use manual cleanup, by passing the address of a pid_t variable
+ * for pid.  While cmd is still in scope, you may reap the child via
+ * virCommandWait or virCommandAbort.  But after virCommandFree, if
+ * you have not yet reaped the child, then it continues to run until
+ * you call virPidWait or virPidAbort.
  */
 int
 virCommandRunAsync(virCommandPtr cmd, pid_t *pid)
@@ -2198,7 +2209,9 @@ int virCommandHandshakeNotify(virCommandPtr cmd)


 /*
- * Release all resources
+ * Release all resources.  The only exception is that if you called
+ * virCommandRunAsync with a non-null pid, then the asynchronous child
+ * is not reaped, and you must call virPidWait() yourself.
  */
 void
 virCommandFree(virCommandPtr cmd)
diff --git i/src/util/command.h w/src/util/command.h
index c8a04f1..f766839 100644
--- i/src/util/command.h
+++ w/src/util/command.h
@@ -366,7 +366,7 @@ void virCommandAbort(virCommandPtr cmd);
 /*
  * Release all resources.  The only exception is that if you called
  * virCommandRunAsync with a non-null pid, then the asynchronous child
- * is not reaped, and you must call waitpid() yourself.
+ * is not reaped, and you must call virPidWait() yourself.
  */
 void virCommandFree(virCommandPtr cmd);



-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 619 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20110714/22b7270e/attachment-0001.sig>