libxl: events: Document and enforce actual callbacks restriction

libxl_event_register_callbacks cannot reasonably be called while libxl
is busy (has outstanding operations and/or enabled events).

This is because the previous spec implied (although not entirely
clearly) that event hooks would not be called for existing fd and
timeout interests.  There is thus no way to reliably ensure that libxl
would get told about fds and timeouts which it became interested in
beforehand.

So there have to be no such fds or timeouts, which means that the
callbacks must only be registered or changed when the ctx is idle.

Document this restriction, and enforce it with a pair of asserts.

(It would be nicer, perhaps, to say that the application may not call
libxl_osevent_register_hooks other than right after creating the ctx.
But there are existing callers, including libvirt, who do it later -
even after doing major operations such as domain creation.)

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Tested-by: Ian Campbell <ian.campbell@citrix.com>
Release-Acked-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

diff --git a/tools/libxl/libxl_event.c b/tools/libxl/libxl_event.c
index a36e6d98ffbc9faa13d788cd95d9d2a39a495784..0d874d9c585e4de89867508c4dda47c7b3d37a38 100644 (file)
--- a/tools/libxl/libxl_event.c
+++ b/tools/libxl/libxl_event.c
@@ -1219,6 +1219,8 @@ void libxl_osevent_register_hooks(libxl_ctx *ctx,
 {
     GC_INIT(ctx);
     CTX_LOCK;
+    assert(LIBXL_LIST_EMPTY(&ctx->efds));
+    assert(LIBXL_TAILQ_EMPTY(&ctx->etimes));
     ctx->osevent_hooks = hooks;
     ctx->osevent_user = user;
     CTX_UNLOCK;

diff --git a/tools/libxl/libxl_event.h b/tools/libxl/libxl_event.h
index b5db83c5f7e1ff00466ef720649ec3bd5b773776..3c6fcfe1b6078ab1800d2f82398dbb0a41ce10fa 100644 (file)
--- a/tools/libxl/libxl_event.h
+++ b/tools/libxl/libxl_event.h
@@ -124,10 +124,8 @@ void libxl_event_register_callbacks(libxl_ctx *ctx,
    * different parameters, as the application likes; the most recent
    * call determines the libxl behaviour.  However it is NOT safe to
    * call _register_callbacks concurrently with, or reentrantly from,
-   * any other libxl function.
-   *
-   * Calls to _register_callbacks do not affect events which have
-   * already occurred.
+   * any other libxl function, nor while any event-generation
+   * facilities are enabled.
    */