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