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

On 07/14/2011 11:34 AM, Matthias Bolte wrote: 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(a)redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org