This callback effectively splits config_complete into "complete the config" and "get ready to start serving". There's no strict need for this new callback, but it makes the API slightly less confusing. --- docs/nbdkit-filter.pod | 38 +++++++++++++++++++++++++------------- docs/nbdkit-plugin.pod | 20 ++++++++++++++++---- include/nbdkit-filter.h | 2 ++ include/nbdkit-plugin.h | 2 ++ server/internal.h | 1 + server/filters.c | 23 +++++++++++++++++++++++ server/main.c | 5 +++++ server/plugins.c | 16 ++++++++++++++++ tests/test-layers-filter.c | 9 +++++++++ tests/test-layers-plugin.c | 8 ++++++++ tests/test-layers.c | 12 ++++++++++++ 11 files changed, 119 insertions(+), 17 deletions(-) diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod index 4105b8b7..a9dffb56 100644 --- a/docs/nbdkit-filter.pod +++ b/docs/nbdkit-filter.pod @@ -127,22 +127,24 @@ which is required. =head1 NEXT PLUGIN F<nbdkit-filter.h> defines some function types (C<nbdkit_next_config>, -C<nbdkit_next_config_complete>, C<nbdkit_next_preconnect>, -C<nbdkit_next_open>) and a structure called C<struct nbdkit_next_ops>. -These abstract the next plugin or filter in the chain. There is also -an opaque pointer C<nxdata> which must be passed along when calling -these functions. The value of C<nxdata> passed to C<.open> has a -stable lifetime that lasts to the corresponding C<.close>, with all -intermediate functions (such as C<.pread>) receiving the same value -for convenience; the only exceptions where C<nxdata> is not reused are -C<.config>, C<.config_complete>, and C<.preconnect>, which are called -outside the lifetime of a connection. +C<nbdkit_next_config_complete>, C<nbdkit_next_get_ready>, +C<nbdkit_next_preconnect>, C<nbdkit_next_open>) and a structure called +C<struct nbdkit_next_ops>. These abstract the next plugin or filter +in the chain. There is also an opaque pointer C<nxdata> which must be +passed along when calling these functions. The value of C<nxdata> +passed to C<.open> has a stable lifetime that lasts to the +corresponding C<.close>, with all intermediate functions (such as +C<.pread>) receiving the same value for convenience; the only +exceptions where C<nxdata> is not reused are C<.config>, +C<.config_complete>, C<.get_ready>, and C<.preconnect>, which are +called outside the lifetime of a connection. =head2 Next config, open and close -The filter’s C<.config>, C<.config_complete> and C<.open> methods may -only call the next C<.config>, C<.config_complete> and C<.open> method -in the chain (optionally for C<.config>). +The filter’s C<.config>, C<.config_complete>, C<.get_ready> and +C<.open> methods may only call the next C<.config>, +C<.config_complete>, C<.get_ready> and C<.open> method in the chain +(optionally for C<.config>). The filter’s C<.close> method is called when an old connection closed, and this has no C<next> parameter because it cannot be @@ -292,6 +294,16 @@ filter doesn't slow down other filters or plugins. If there is an error, C<.thread_model> should call C<nbdkit_error> with an error message and return C<-1>. +=head2 C<.get_ready> + + int (*get_ready) (nbdkit_next_get_ready *next, void *nxdata); + +This intercepts the plugin C<.get_ready> method and can be used by the +filter to get ready to serve requests. + +If there is an error, C<.get_ready> should call C<nbdkit_error> with +an error message and return C<-1>. + =head2 C<.preconnect> int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata, diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod index 41bffb7f..77f1a098 100644 --- a/docs/nbdkit-plugin.pod +++ b/docs/nbdkit-plugin.pod @@ -443,6 +443,18 @@ are silently ignored. If there is an error, C<.thread_model> should call C<nbdkit_error> with an error message and return C<-1>. +=head2 C<.get_ready> + + int get_ready (void); + +This optional callback is called before the server starts serving. It +is called before the server forks or changes directory. It is the +last chance to do any global preparation that is needed to serve +connections. + +If there is an error, C<.get_ready> should call C<nbdkit_error> with +an error message and return C<-1>. + =head2 C<.preconnect> int preconnect (int readonly); @@ -1182,8 +1194,8 @@ absolute path: if it is relative, then all this function does is prepend the current working directory to the path, with no extra checks. -Note that this function works I<only> when used in the C<.config>, and -C<.config_complete> callbacks. +Note that this function works I<only> when used in the C<.config>, +C<.config_complete> and C<.get_ready> callbacks. If conversion was not possible, this calls C<nbdkit_error> and returns C<NULL>. Note that this function does not check that the file exists. @@ -1199,8 +1211,8 @@ absolute path, resolving symlinks. Under the hood it uses the C<realpath> function, and thus it fails if the path does not exist, or it is not possible to access to any of the components of the path. -Note that this function works I<only> when used in the C<.config>, and -C<.config_complete> callbacks. +Note that this function works I<only> when used in the C<.config>, +C<.config_complete> and C<.get_ready> callbacks. If the path resolution was not possible, this calls C<nbdkit_error> and returns C<NULL>. diff --git a/include/nbdkit-filter.h b/include/nbdkit-filter.h index a44c689b..ca58e496 100644 --- a/include/nbdkit-filter.h +++ b/include/nbdkit-filter.h @@ -62,6 +62,7 @@ typedef void nbdkit_backend; typedef int nbdkit_next_config (nbdkit_backend *nxdata, const char *key, const char *value); typedef int nbdkit_next_config_complete (nbdkit_backend *nxdata); +typedef int nbdkit_next_get_ready (nbdkit_backend *nxdata); typedef int nbdkit_next_preconnect (nbdkit_backend *nxdata, int readonly); typedef int nbdkit_next_open (nbdkit_backend *nxdata, int readonly); @@ -143,6 +144,7 @@ struct nbdkit_filter { nbdkit_backend *nxdata); const char *config_help; int (*thread_model) (void); + int (*get_ready) (nbdkit_next_get_ready *next, nbdkit_backend *nxdata); int (*preconnect) (nbdkit_next_preconnect *next, nbdkit_backend *nxdata, int readonly); diff --git a/include/nbdkit-plugin.h b/include/nbdkit-plugin.h index b4ecf658..7e06a4b1 100644 --- a/include/nbdkit-plugin.h +++ b/include/nbdkit-plugin.h @@ -136,6 +136,8 @@ struct nbdkit_plugin { int (*can_fast_zero) (void *handle); int (*preconnect) (int readonly); + + int (*get_ready) (void); }; extern void nbdkit_set_error (int err); diff --git a/server/internal.h b/server/internal.h index eaec31ba..d8a589f2 100644 --- a/server/internal.h +++ b/server/internal.h @@ -344,6 +344,7 @@ struct backend { void (*config) (struct backend *, const char *key, const char *value); void (*config_complete) (struct backend *); const char *(*magic_config_key) (struct backend *); + void (*get_ready) (struct backend *); int (*preconnect) (struct backend *, int readonly); void *(*open) (struct backend *, int readonly); int (*prepare) (struct backend *, void *handle, int readonly); diff --git a/server/filters.c b/server/filters.c index 8985ebeb..f0371066 100644 --- a/server/filters.c +++ b/server/filters.c @@ -171,6 +171,28 @@ filter_config_complete (struct backend *b) b->next->config_complete (b->next); } +static int +next_get_ready (struct backend *b) +{ + b->get_ready (b); + return 0; +} + +static void +filter_get_ready (struct backend *b) +{ + struct backend_filter *f = container_of (b, struct backend_filter, backend); + + debug ("%s: get_ready", b->name); + + if (f->filter.get_ready) { + if (f->filter.get_ready (next_get_ready, b->next) == -1) + exit (EXIT_FAILURE); + } + else + b->next->get_ready (b->next); +} + static int filter_preconnect (struct backend *b, int readonly) { @@ -493,6 +515,7 @@ static struct backend filter_functions = { .config = filter_config, .config_complete = filter_config_complete, .magic_config_key = plugin_magic_config_key, + .get_ready = filter_get_ready, .preconnect = filter_preconnect, .open = filter_open, .prepare = filter_prepare, diff --git a/server/main.c b/server/main.c index 3cfd1e2e..6350d110 100644 --- a/server/main.c +++ b/server/main.c @@ -694,6 +694,11 @@ main (int argc, char *argv[]) exit (EXIT_FAILURE); } + /* Tell the plugin that we are about to start serving. This must be + * called before we change user, fork, or open any sockets. + */ + top->get_ready (top); + start_serving (); top->free (top); diff --git a/server/plugins.c b/server/plugins.c index 16b4099b..78ed6723 100644 --- a/server/plugins.c +++ b/server/plugins.c @@ -158,6 +158,7 @@ plugin_dump_fields (struct backend *b) HAS (config); HAS (config_complete); HAS (config_help); + HAS (get_ready); HAS (preconnect); HAS (open); HAS (close); @@ -234,6 +235,20 @@ plugin_magic_config_key (struct backend *b) return p->plugin.magic_config_key; } +static void +plugin_get_ready (struct backend *b) +{ + struct backend_plugin *p = container_of (b, struct backend_plugin, backend); + + debug ("%s: get_ready", b->name); + + if (!p->plugin.get_ready) + return; + + if (p->plugin.get_ready () == -1) + exit (EXIT_FAILURE); +} + static int plugin_preconnect (struct backend *b, int readonly) { @@ -670,6 +685,7 @@ static struct backend plugin_functions = { .config = plugin_config, .config_complete = plugin_config_complete, .magic_config_key = plugin_magic_config_key, + .get_ready = plugin_get_ready, .preconnect = plugin_preconnect, .open = plugin_open, .prepare = plugin_prepare, diff --git a/tests/test-layers-filter.c b/tests/test-layers-filter.c index 44f62c6e..53427d2a 100644 --- a/tests/test-layers-filter.c +++ b/tests/test-layers-filter.c @@ -81,6 +81,14 @@ test_layers_filter_config_complete (nbdkit_next_config_complete *next, #define test_layers_filter_config_help \ "test_layers_" layer "_config_help" +static int +test_layers_filter_get_ready (nbdkit_next_get_ready *next, + void *nxdata) +{ + DEBUG_FUNCTION; + return next (nxdata); +} + static int test_layers_filter_preconnect (nbdkit_next_preconnect *next, void *nxdata, int readonly) @@ -349,6 +357,7 @@ static struct nbdkit_filter filter = { .config = test_layers_filter_config, .config_complete = test_layers_filter_config_complete, .config_help = test_layers_filter_config_help, + .get_ready = test_layers_filter_get_ready, .preconnect = test_layers_filter_preconnect, .open = test_layers_filter_open, .close = test_layers_filter_close, diff --git a/tests/test-layers-plugin.c b/tests/test-layers-plugin.c index 10cc6efe..8858bede 100644 --- a/tests/test-layers-plugin.c +++ b/tests/test-layers-plugin.c @@ -72,6 +72,13 @@ test_layers_plugin_config_complete (void) #define test_layers_plugin_config_help "test_layers_plugin_config_help" +static int +test_layers_plugin_get_ready (void) +{ + DEBUG_FUNCTION; + return 0; +} + static int test_layers_plugin_preconnect (int readonly) { @@ -231,6 +238,7 @@ static struct nbdkit_plugin plugin = { .config = test_layers_plugin_config, .config_complete = test_layers_plugin_config_complete, .config_help = test_layers_plugin_config_help, + .get_ready = test_layers_plugin_get_ready, .preconnect = test_layers_plugin_preconnect, .open = test_layers_plugin_open, .close = test_layers_plugin_close, diff --git a/tests/test-layers.c b/tests/test-layers.c index fafe68c4..33ae5a75 100644 --- a/tests/test-layers.c +++ b/tests/test-layers.c @@ -288,6 +288,18 @@ main (int argc, char *argv[]) "test_layers_plugin_config_complete", NULL); + /* get_ready methods called in order. */ + log_verify_seen_in_order + ("testlayersfilter3: get_ready", + "filter3: test_layers_filter_get_ready", + "testlayersfilter2: get_ready", + "filter2: test_layers_filter_get_ready", + "testlayersfilter1: get_ready", + "filter1: test_layers_filter_get_ready", + "testlayersplugin: get_ready", + "test_layers_plugin_get_ready", + NULL); + /* preconnect methods called in outer-to-inner order, complete * in inner-to-outer order. */ -- 2.25.0

--- plugins/ocaml/ocaml.c | 25 +++++++++++++++++++++++++ plugins/ocaml/NBDKit.ml | 8 ++++++++ plugins/ocaml/NBDKit.mli | 2 ++ tests/test_ocaml_plugin.ml | 6 ++++++ 4 files changed, 41 insertions(+) diff --git a/plugins/ocaml/ocaml.c b/plugins/ocaml/ocaml.c index 619a678b..82003343 100644 --- a/plugins/ocaml/ocaml.c +++ b/plugins/ocaml/ocaml.c @@ -106,6 +106,8 @@ static value config_fn; static value config_complete_fn; static value thread_model_fn; +static value get_ready_fn; + static value preconnect_fn; static value open_fn; static value close_fn; @@ -238,6 +240,25 @@ thread_model_wrapper (void) CAMLreturnT (int, Int_val (rv)); } +static int +get_ready_wrapper (void) +{ + CAMLparam0 (); + CAMLlocal1 (rv); + + caml_leave_blocking_section (); + + rv = caml_callback_exn (get_ready_fn, Val_unit); + if (Is_exception_result (rv)) { + nbdkit_error ("%s", caml_format_exception (Extract_exception (rv))); + caml_enter_blocking_section (); + CAMLreturnT (int, -1); + } + + caml_enter_blocking_section (); + CAMLreturnT (int, 0); +} + static int preconnect_wrapper (int readonly) { @@ -799,6 +820,8 @@ SET(config) SET(config_complete) SET(thread_model) +SET(get_ready) + SET(preconnect) SET(open) SET(close) @@ -840,6 +863,8 @@ remove_roots (void) REMOVE (config_complete); REMOVE (thread_model); + REMOVE (get_ready); + REMOVE (preconnect); REMOVE (open); REMOVE (close); diff --git a/plugins/ocaml/NBDKit.ml b/plugins/ocaml/NBDKit.ml index e3b07ab5..ed636c72 100644 --- a/plugins/ocaml/NBDKit.ml +++ b/plugins/ocaml/NBDKit.ml @@ -69,6 +69,8 @@ type 'a plugin = { config_help : string; thread_model : (unit -> thread_model) option; + get_ready : (unit -> unit) option; + preconnect : (bool -> unit) option; open_connection : (bool -> 'a) option; close : ('a -> unit) option; @@ -111,6 +113,8 @@ let default_callbacks = { config_help = ""; thread_model = None; + get_ready = None; + preconnect = None; open_connection = None; close = None; @@ -152,6 +156,8 @@ external set_config_complete : (unit -> unit) -> unit = "ocaml_nbdkit_set_config external set_config_help : string -> unit = "ocaml_nbdkit_set_config_help" "noalloc" external set_thread_model : (unit -> thread_model) -> unit = "ocaml_nbdkit_set_thread_model" +external set_get_ready : (unit -> unit) -> unit = "ocaml_nbdkit_set_get_ready" + external set_preconnect : (bool -> unit) -> unit = "ocaml_nbdkit_set_preconnect" external set_open : (bool -> 'a) -> unit = "ocaml_nbdkit_set_open" external set_close : ('a -> unit) -> unit = "ocaml_nbdkit_set_close" @@ -214,6 +220,8 @@ let register_plugin plugin = set_config_help plugin.config_help; may set_thread_model plugin.thread_model; + may set_get_ready plugin.get_ready; + may set_preconnect plugin.preconnect; may set_open plugin.open_connection; may set_close plugin.close; diff --git a/plugins/ocaml/NBDKit.mli b/plugins/ocaml/NBDKit.mli index 8cc4fed2..78019442 100644 --- a/plugins/ocaml/NBDKit.mli +++ b/plugins/ocaml/NBDKit.mli @@ -74,6 +74,8 @@ type 'a plugin = { config_help : string; thread_model : (unit -> thread_model) option; + get_ready : (unit -> unit) option; + preconnect : (bool -> unit) option; open_connection : (bool -> 'a) option; (* required *) close : ('a -> unit) option; diff --git a/tests/test_ocaml_plugin.ml b/tests/test_ocaml_plugin.ml index 3cf8fd90..753e51ab 100644 --- a/tests/test_ocaml_plugin.ml +++ b/tests/test_ocaml_plugin.ml @@ -19,6 +19,12 @@ let test_config_complete () = let params = List.rev !params in assert (params = [ "a", "1"; "b", "2"; "c", "3" ]) +let test_get_ready () = + (* We could allocate the disk here, but it's easier to allocate + * it statically above. + *) + NBDKit.debug "test ocaml plugin getting ready" + let test_open readonly = NBDKit.debug "test ocaml plugin handle opened readonly=%b" readonly; () -- 2.25.0

--- plugins/eval/nbdkit-eval-plugin.pod | 2 ++ plugins/sh/nbdkit-sh-plugin.pod | 4 ++++ plugins/sh/methods.h | 1 + plugins/eval/eval.c | 2 ++ plugins/sh/methods.c | 25 +++++++++++++++++++++++++ plugins/sh/sh.c | 1 + tests/test-eval.sh | 1 + 7 files changed, 36 insertions(+) diff --git a/plugins/eval/nbdkit-eval-plugin.pod b/plugins/eval/nbdkit-eval-plugin.pod index a3601333..602fd3aa 100644 --- a/plugins/eval/nbdkit-eval-plugin.pod +++ b/plugins/eval/nbdkit-eval-plugin.pod @@ -100,6 +100,8 @@ features): =item B<flush=>SCRIPT +=item B<get_ready=>SCRIPT + =item B<get_size=>SCRIPT =item B<is_rotational=>SCRIPT diff --git a/plugins/sh/nbdkit-sh-plugin.pod b/plugins/sh/nbdkit-sh-plugin.pod index 2f265b05..ffd0310f 100644 --- a/plugins/sh/nbdkit-sh-plugin.pod +++ b/plugins/sh/nbdkit-sh-plugin.pod @@ -246,6 +246,10 @@ actually gets selected. If an error occurs, the script should output an error message and exit with status C<1>; unrecognized output is ignored. +=item C<get_ready> + + /path/to/script get_ready + =item C<preconnect> /path/to/script preconnect <readonly> <exportname> diff --git a/plugins/sh/methods.h b/plugins/sh/methods.h index 8a8f179c..f11e67e7 100644 --- a/plugins/sh/methods.h +++ b/plugins/sh/methods.h @@ -41,6 +41,7 @@ extern const char *get_script (const char *method); extern void sh_dump_plugin (void); extern int sh_thread_model (void); +extern int sh_get_ready (void); extern int sh_preconnect (int readonly); extern void *sh_open (int readonly); extern void sh_close (void *handle); diff --git a/plugins/eval/eval.c b/plugins/eval/eval.c index 9071b8c7..f09e49f3 100644 --- a/plugins/eval/eval.c +++ b/plugins/eval/eval.c @@ -70,6 +70,7 @@ static const char *known_methods[] = { "dump_plugin", "extents", "flush", + "get_ready", "get_size", "is_rotational", "missing", @@ -409,6 +410,7 @@ static struct nbdkit_plugin plugin = { .config_complete = eval_config_complete, .config_help = eval_config_help, .thread_model = sh_thread_model, + .get_ready = sh_get_ready, .preconnect = sh_preconnect, .open = sh_open, diff --git a/plugins/sh/methods.c b/plugins/sh/methods.c index e8011284..56e2d410 100644 --- a/plugins/sh/methods.c +++ b/plugins/sh/methods.c @@ -139,6 +139,31 @@ sh_thread_model (void) } } +int +sh_get_ready (void) +{ + const char *method = "get_ready"; + const char *script = get_script (method); + const char *args[] = { script, method, NULL }; + + switch (call (args)) { + case OK: + case MISSING: + return 0; + + case ERROR: + return -1; + + case RET_FALSE: + nbdkit_error ("%s: %s method returned unexpected code (3/false)", + script, method); + errno = EIO; + return -1; + + default: abort (); + } +} + int sh_preconnect (int readonly) { diff --git a/plugins/sh/sh.c b/plugins/sh/sh.c index 0d24edb4..736b8ef0 100644 --- a/plugins/sh/sh.c +++ b/plugins/sh/sh.c @@ -310,6 +310,7 @@ static struct nbdkit_plugin plugin = { .config_help = sh_config_help, .magic_config_key = "script", .thread_model = sh_thread_model, + .get_ready = sh_get_ready, .preconnect = sh_preconnect, .open = sh_open, diff --git a/tests/test-eval.sh b/tests/test-eval.sh index 868452f3..da7b8861 100755 --- a/tests/test-eval.sh +++ b/tests/test-eval.sh @@ -59,6 +59,7 @@ grep 'in missing: config_complete' eval.missing grep 'in missing: thread_model' eval.missing grep 'in missing: can_write' eval.missing grep 'in missing: is_rotational' eval.missing +grep 'in missing: get_ready' eval.missing grep 'in missing: preconnect' eval.missing grep 'in missing: open' eval.missing grep 'in missing: close' eval.missing -- 2.25.0