[Libguestfs] [nbdkit PATCH 3/3] server: Add and use nbdkit_nanosleep

[Richard W.M. Jones]

On Sat, Aug 03, 2019 at 11:01:44AM -0500, Eric Blake wrote:
[...]

ACK series, but ...

> +=head2 C<nbdkit_nanosleep>
> +
[...]
> +This is similar to L<nanosleep(3)>, although you specify the
> +components as separate parameters rather than as a C<struct timespec>.
> +This wrapper provides two benefits over the system library: in one
> +direction, the system library has no easy way to abort a sleep early
> +if other information determines that there is no point in finishing
> +the sleep (handling a signal in the same thread as the sleep will do
> +that, but you don't have full control over the signal masks of other
> +threads to ensure that your thread will get the intended interrupting
> +signal).  In the other direction, the system library has no easy way
> +to avoid aborting a sleep early (you can restart the sleep with any
> +remaining unslept time, but calculating this gets tedious; or you can
> +use signal masks to avoid handling a signal, but risk making your
> +thread non-responsive to signals that were important after all,
> +stalling a timely shutdown of nbdkit).  The system call L<ppoll(2)>
> +can solve these issues, but requires access to internal file
> +descriptors that the plugin does not need access to, hence this
> +function exists to do the work on your behalf.

Do we really need this paragraph?  It's explaining how
nbdkit_nanosleep works internally which might change in future and is
largely irrelevant to plugin designers.  I'd say something along the
lines of:

  Plugins should prefer this function instead of sleeping using system
  calls like L<sleep(2)> or L<nanosleep(3)>, since it allows nbdkit to
  shut down cleanly without delay.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v