[Libguestfs] [PATCH nbdkit filters-v3 3/7] Introduce filters.

[Eric Blake]

On 01/19/2018 04:36 PM, Richard W.M. Jones wrote:
> Filters can be placed in front of plugins to modify their behaviour.
> 
> This commit adds the <nbdkit-filter.h> header file, the manual page,
> the ‘filterdir’ directory (like ‘plugindir’), the ‘filters/’ source
> directory which will contain the actual filters, the ‘--filters’
> parameter, and the filters backend logic.
> ---

> +
> +The filter’s C<.open> and C<.close> methods are called when a new
> +connection is opened or an old connection closed, and these have no
> +C<next> parameter because they cannot be short-circuited.
> +

Stale, given [1]

> +
> +=head2 C<.limit_thread_model>
> +
> + int (*limit_thread_model) (void);

Does this need to be a callback, or can it just be a compile-time value
the way plugins have a compile-time value?  The backend has to have a
function, to find the most restrictive model in the chain, but I'm not
seeing how a filter would have a different model depending on how many
times .open has been called, so exposing it as a function in the filter
seems overkill.

> +
> +A filter may define this to make the plugin thread model more limited
> +if, for some reason, the filter is unable to handle parallel requests.
> +The callback, if defined, should return one of the
> +C<NBDKIT_THREAD_MODEL_*> values (see L<nbdkit-plugin(3)>).
> +
> +The final thread model is the smallest (ie. most serialized) out of
> +all the filters and the plugin.  Filters cannot alter the thread model
> +to make it larger (more parallel).
> +
> +If this callback is not defined then the filter must be prepared to
> +handle fully parallel requests (like C<NBDKIT_THREAD_MODEL_PARALLEL>),
> +even multiple requests issued in parallel on the same connection.

This part is good, whether you go with a callback or a define.


> +=head2 C<.open>
> +
> + void * (*open) (nbdkit_next_open *next, void *nxdata,
> +                 int readonly);

[1] this new signature.

> +
> +This is called when a new client connection is opened and can be used
> +to allocate any per-connection data structures needed by the filter.
> +The handle (which is not the same as the plugin handle) is passed back
> +to other filter callbacks and could be freed in the C<.close>
> +callback.
> +
> +Note that the handle is completely opaque to nbdkit, but it must not
> +be NULL.
> +
> +If there is an error, C<.open> should call C<nbdkit_error> with an
> +error message and return C<NULL>.

No documentation about setting the underlying layers read-only (useful
in a copy-on-write or copy-on-read filter)?  Also, is it possible to
write a filter that is read-only to the client, but must be able to
write to the plugin?

> +++ b/include/nbdkit-filter.h
> +++ b/src/filters.c

> +++ b/src/internal.h
> @@ -41,6 +41,7 @@
>  #include <pthread.h>
>  
>  #include "nbdkit-plugin.h"
> +#include "nbdkit-filter.h"

Hmm, my idea about preventing inclusion of both files at once won't work
here.  We may still want to prevent a single .so from declaring both a
filter and a plugin, but that has to be done by means other than
mutually-exclusive inclusion.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | 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/libguestfs/attachments/20180119/f54e44e0/attachment.sig>