Re: [Libguestfs] [PATCH nbdkit filters-v3 3/7] Introduce filters.
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
Attachments:
- signature.asc (application/pgp-signature — 619 bytes)