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
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Libguestfs mailing list [email protected] https://www.redhat.com/mailman/listinfo/libguestfs
