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