diff options
author | Ian Jackson <ian.jackson@eu.citrix.com> | 2012-05-11 18:59:05 +0100 |
---|---|---|
committer | Ian Jackson <ian.jackson@eu.citrix.com> | 2012-05-11 18:59:05 +0100 |
commit | 254a9c4a28e9d35426bb098a2d52c035b8f1e416 (patch) | |
tree | 20bf0ef4edb229b13c6915d3aa66ec422bbbd765 /tools/libxl/libxl.h | |
parent | 738b3d44252221ed3be1a860366a15a2d1b9b091 (diff) | |
download | xen-254a9c4a28e9d35426bb098a2d52c035b8f1e416.tar.gz xen-254a9c4a28e9d35426bb098a2d52c035b8f1e416.tar.bz2 xen-254a9c4a28e9d35426bb098a2d52c035b8f1e416.zip |
libxl: provide progress reporting for long-running operations
This will be used for reporting, during domain creation, that the
console is ready.
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Changes since v7:
* If aop->how.callback, actually add the aop to the for_callback list (!)
* Document the threadsafety of aop's, and make appropriate cross-references.
* Allocate the actual aop from its thread's egc; do not free it.
* Remove pointless code motion of libxl__ao_create.
* Minor formatting fixes.
Committed-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Diffstat (limited to 'tools/libxl/libxl.h')
-rw-r--r-- | tools/libxl/libxl.h | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h index e19d947ef9..ba0f4dee4b 100644 --- a/tools/libxl/libxl.h +++ b/tools/libxl/libxl.h @@ -435,6 +435,51 @@ typedef struct { } u; } libxl_asyncop_how; +/* + * Some more complex asynchronous operations can report intermediate + * progress. How this is to be reported is controlled, for each + * function, by a parameter + * libxl_asyncprogress_how *aop_FOO_how; + * for each kind of progress FOO supported by that function. Each + * such kind of progress is associated with an event type. + * + * The function description will document whether, when, and how + * many times, the intermediate progress will be reported, and + * what the corresponding event type(s) are. + * + * If aop_FOO_how==NULL, intermediate progress reports are discarded. + * + * If aop_FOO_how->callback==NULL, intermediate progress reports + * generate libxl events which can be obtained from libxl_event_wait + * or libxl_event_check. + * + * If aop_FOO_how->callback!=NULL, libxl will report intermediate + * progress by calling callback(ctx, &event, for_callback). + * + * The rules for these events are otherwise the same as those for + * ordinary events. The reentrancy and threading rules for the + * callback are the same as those for ao completion callbacks. + * + * Note that the callback, if provided, is responsible for freeing + * the event. + * + * If callbacks are requested, they will be made, and returned, before + * the long-running libxl operation is considered finished (so if the + * long-running libxl operation was invoked with ao_how==NULL then any + * callbacks will occur strictly before the long-running operation + * returns). However, the callbacks may occur on any thread. + * + * In general, otherwise, no promises are made about the relative + * order of callbacks in a multithreaded program. In particular + * different callbacks relating to the same long-running operation may + * be delivered out of order. + */ + +typedef struct { + void (*callback)(libxl_ctx *ctx, libxl_event*, void *for_callback); + libxl_ev_user for_event; /* always used */ + void *for_callback; /* passed to callback */ +} libxl_asyncprogress_how; #define LIBXL_VERSION 0 |