diff options
Diffstat (limited to 'tools/include/libxl_event.h')
| -rw-r--r-- | tools/include/libxl_event.h | 632 |
1 files changed, 632 insertions, 0 deletions
diff --git a/tools/include/libxl_event.h b/tools/include/libxl_event.h new file mode 100644 index 0000000000..8d0aa6417e --- /dev/null +++ b/tools/include/libxl_event.h @@ -0,0 +1,632 @@ +/* + * Copyright (C) 2011 Citrix Ltd. + * Author Ian Jackson <ian.jackson@eu.citrix.com> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as published + * by the Free Software Foundation; version 2.1 only. with the special + * exception on linking described in file LICENSE. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +#ifndef LIBXL_EVENT_H +#define LIBXL_EVENT_H + +#include <libxl.h> +#include <poll.h> +#include <sys/time.h> + +/*======================================================================*/ + +/* + * Domain event handling - getting Xen events from libxl + * + * (Callers inside libxl may not call libxl_event_check or _wait.) + */ + +#define LIBXL_EVENTMASK_ALL (~(unsigned long)0) + +typedef int libxl_event_predicate(const libxl_event*, void *user); + /* Return value is 0 if the event is unwanted or non-0 if it is. + * Predicates are not allowed to fail. + */ + +int libxl_event_check(libxl_ctx *ctx, libxl_event **event_r, + uint64_t typemask, + libxl_event_predicate *predicate, void *predicate_user) + LIBXL_EXTERNAL_CALLERS_ONLY; + /* Searches for an event, already-happened, which matches typemask + * and predicate. predicate==0 matches any event. + * libxl_event_check returns the event, which must then later be + * freed by the caller using libxl_event_free. + * + * Returns ERROR_NOT_READY if no such event has happened. + */ + +int libxl_event_wait(libxl_ctx *ctx, libxl_event **event_r, + uint64_t typemask, + libxl_event_predicate *predicate, void *predicate_user) + LIBXL_EXTERNAL_CALLERS_ONLY; + /* Like libxl_event_check but blocks if no suitable events are + * available, until some are. Uses libxl_osevent_beforepoll/ + * _afterpoll so may be inefficient if very many domains are being + * handled by a single program. + */ + +void libxl_event_free(libxl_ctx *ctx, libxl_event *event); + + +/* Alternatively or additionally, the application may also use this: */ + +typedef struct libxl_event_hooks { + uint64_t event_occurs_mask; + void (*event_occurs)(void *user, +#ifndef LIBXL_HAVE_NONCONST_EVENT_OCCURS_EVENT_ARG + const +#endif + libxl_event *event); + void (*disaster)(void *user, libxl_event_type type, + const char *msg, int errnoval); +} libxl_event_hooks; + +void libxl_event_register_callbacks(libxl_ctx *ctx, + const libxl_event_hooks *hooks, void *user); + /* + * Arranges that libxl will henceforth call event_occurs for any + * events whose type is set in event_occurs_mask, rather than + * queueing the event for retrieval by libxl_event_check/wait. + * Events whose bit is clear in mask are not affected. + * + * event becomes owned by the application and must be freed, either + * by event_occurs or later. + * + * event_occurs may be NULL if mask is 0. + * + * libxl_event_register_callback also provides a way for libxl to + * report to the application that there was a problem reporting + * events; this can occur due to lack of host memory during event + * handling, or other wholly unrecoverable errors from system calls + * made by libxl. This will not happen for frivolous reasons - only + * if the system, or the Xen components of it, are badly broken. + * + * msg and errnoval will describe the action that libxl was trying + * to do, and type specifies the type of libxl events which may be + * missing. type may be 0 in which case events of all types may be + * missing. + * + * disaster may be NULL. If it is, or if _register_callbacks has + * not been called, errors of this kind are fatal to the entire + * application: libxl will print messages to its logs and to stderr + * and call exit(-1). + * + * If disaster returns, it may be the case that some or all future + * libxl calls will return errors; likewise it may be the case that + * no more events (of the specified type, if applicable) can be + * produced. An application which supplies a disaster function + * should normally react either by exiting, or by (when it has + * returned to its main event loop) shutting down libxl with + * libxl_ctx_free and perhaps trying to restart it with + * libxl_ctx_init. + * + * In any case before calling disaster, libxl will have logged a + * message with level XTL_CRITICAL. + * + * Reentrancy: it IS permitted to call libxl from within + * event_occurs. It is NOT permitted to call libxl from within + * disaster. The event_occurs and disaster callbacks may occur on + * any thread in which the application calls libxl. + * + * libxl_event_register_callbacks may be called as many times, with + * 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, nor while any event-generation + * facilities are enabled. + */ + + +/* + * Events are only generated if they have been requested. + * The following functions request the generation of specific events. + * + * Each set of functions for controlling event generation has this form: + * + * typedef struct libxl__evgen_FOO libxl__evgen_FOO; + * int libxl_evenable_FOO(libxl_ctx *ctx, FURTHER PARAMETERS, + * libxl_ev_user user, libxl__evgen_FOO **evgen_out); + * void libxl_evdisable_FOO(libxl_ctx *ctx, libxl__evgen_FOO *evgen); + * + * The evenable function arranges that the events (as described in the + * doc comment for the individual function) will start to be generated + * by libxl. On success, *evgen_out is set to a non-null pointer to + * an opaque struct. + * + * The user value is returned in the generated events and may be + * used by the caller for whatever it likes. The type ev_user is + * guaranteed to be an unsigned integer type which is at least + * as big as uint64_t and is also guaranteed to be big enough to + * contain any intptr_t value. + * + * If it becomes desirable to stop generation of the relevant events, + * or to reclaim the resources in libxl associated with the evgen + * structure, the same evgen value should be passed to the evdisable + * function. However, note that events which occurred prior to the + * evdisable call may still be returned. + * + * The caller may enable identical events more than once. If they do + * so, each actual occurrence will generate several events to be + * returned by libxl_event_check, with the appropriate user value(s). + * Aside from this, each occurrence of each event is returned by + * libxl_event_check exactly once. + * + * An evgen is associated with the libxl_ctx used for its creation. + * After libxl_ctx_free, all corresponding evgen handles become + * invalid and must no longer be passed to evdisable. + * + * Applications should ensure that they eventually retrieve every + * event using libxl_event_check or libxl_event_wait, since events + * which occur but are not retrieved by the application will be queued + * inside libxl indefinitely. libxl_event_check/_wait may be O(n) + * where n is the number of queued events which do not match the + * criteria specified in the arguments to check/wait. + */ + +typedef struct libxl__evgen_domain_death libxl_evgen_domain_death; +int libxl_evenable_domain_death(libxl_ctx *ctx, uint32_t domid, + libxl_ev_user, libxl_evgen_domain_death **evgen_out); +void libxl_evdisable_domain_death(libxl_ctx *ctx, libxl_evgen_domain_death*); + /* Arranges for the generation of DOMAIN_SHUTDOWN and DOMAIN_DEATH + * events. A domain which is destroyed before it shuts down + * may generate only a DEATH event. + */ + +typedef struct libxl__evgen_disk_eject libxl_evgen_disk_eject; +int libxl_evenable_disk_eject(libxl_ctx *ctx, uint32_t domid, const char *vdev, + libxl_ev_user, libxl_evgen_disk_eject **evgen_out); +void libxl_evdisable_disk_eject(libxl_ctx *ctx, libxl_evgen_disk_eject*); + /* Arranges for the generation of DISK_EJECT events. A copy of the + * string *vdev will be made for libxl's internal use, and a pointer + * to this (or some other) copy will be returned as the vdev + * member of event.u. + */ + + +/*======================================================================*/ + +/* + * OS event handling - passing low-level OS events to libxl + * + * Event-driven programs must use these facilities to allow libxl + * to become aware of readability/writeability of file descriptors + * and the occurrence of timeouts. + * + * There are two approaches available. The first is appropriate for + * simple programs handling reasonably small numbers of domains: + * + * for (;;) { + * libxl_osevent_beforepoll(...) + * poll(); + * libxl_osevent_afterpoll(...); + * for (;;) { + * r = libxl_event_check(...); + * if (r==ERROR_NOT_READY) break; + * if (r) goto error_out; + * do something with the event; + * } + * } + * + * The second approach uses libxl_osevent_register_hooks and is + * suitable for programs which are already using a callback-based + * event library. + * + * An application may freely mix the two styles of interaction. + * + * (Callers inside libxl may not call libxl_osevent_... functions.) + */ + +struct pollfd; + +/* The caller should provide beforepoll with some space for libxl's + * fds, and tell libxl how much space is available by setting *nfds_io. + * fds points to the start of this space (and fds may be a pointer into + * a larger array, for example, if the application has some fds of + * its own that it is interested in). + * + * On return *nfds_io will in any case have been updated by libxl + * according to how many fds libxl wants to poll on. + * + * If the space was sufficient, libxl fills in fds[0..<new + * *nfds_io>] suitably for poll(2), updates *timeout_upd if needed, + * and returns ok. + * + * If space was insufficient, fds[0..<old *nfds_io>] is undefined on + * return; *nfds_io on return will be greater than the value on + * entry; *timeout_upd may or may not have been updated; and + * libxl_osevent_beforepoll returns ERROR_BUFERFULL. In this case + * the application needs to make more space (enough space for + * *nfds_io struct pollfd) and then call beforepoll again, before + * entering poll(2). Typically this will involve calling realloc. + * + * The application may call beforepoll with fds==NULL and + * *nfds_io==0 in order to find out how much space is needed. + * + * *timeout_upd is as for poll(2): it's in milliseconds, and + * negative values mean no timeout (infinity). + * libxl_osevent_beforepoll will only reduce the timeout, naturally. + */ +int libxl_osevent_beforepoll(libxl_ctx *ctx, int *nfds_io, + struct pollfd *fds, int *timeout_upd, + struct timeval now) + LIBXL_EXTERNAL_CALLERS_ONLY; + +/* nfds and fds[0..nfds] must be from the most recent call to + * _beforepoll, as modified by poll. (It is therefore not possible + * to have multiple threads simultaneously polling using this + * interface.) + * + * This function actually performs all of the IO and other actions, + * and generates events (libxl_event), which are implied by either + * (a) the time of day or (b) both (i) the returned information from + * _beforepoll, and (ii) the results from poll specified in + * fds[0..nfds-1]. Generated events can then be retrieved by + * libxl_event_check. + */ +void libxl_osevent_afterpoll(libxl_ctx *ctx, int nfds, const struct pollfd *fds, + struct timeval now) + LIBXL_EXTERNAL_CALLERS_ONLY; + + +typedef struct libxl_osevent_hooks { + int (*fd_register)(void *user, int fd, void **for_app_registration_out, + short events, void *for_libxl); + int (*fd_modify)(void *user, int fd, void **for_app_registration_update, + short events); + void (*fd_deregister)(void *user, int fd, void *for_app_registration); + int (*timeout_register)(void *user, void **for_app_registration_out, + struct timeval abs, void *for_libxl); + int (*timeout_modify)(void *user, void **for_app_registration_update, + struct timeval abs) + /* only ever called with abs={0,0}, meaning ASAP */; + void (*timeout_deregister)(void *user, void *for_app_registration) + /* will never be called */; +} libxl_osevent_hooks; + +/* The application which calls register_fd_hooks promises to + * maintain a register of fds and timeouts that libxl is interested + * in, and make calls into libxl (libxl_osevent_occurred_*) + * when those fd events and timeouts occur. This is more efficient + * than _beforepoll/_afterpoll if there are many fds (which can + * happen if the same libxl application is managing many domains). + * + * For an fd event, events is as for poll(). register or modify may + * be called with events==0, in which case it must still work + * normally, just not generate any events. + * + * For a timeout event, milliseconds is as for poll(). + * Specifically, negative values of milliseconds mean NO TIMEOUT. + * This is used by libxl to temporarily disable a timeout. + * + * If the register or modify hook succeeds it may update + * *for_app_registration_out/_update and must then return 0. + * On entry to register, *for_app_registration_out is always NULL. + * + * A registration or modification hook may fail, in which case it + * must leave the registration state of the fd or timeout unchanged. + * It may then either return ERROR_OSEVENT_REG_FAIL or any positive + * int. The value returned will be passed up through libxl and + * eventually returned back to the application. When register + * fails, any value stored into *for_registration_out is ignored by + * libxl; when modify fails, any changed value stored into + * *for_registration_update is honoured by libxl and will be passed + * to future modify or deregister calls. + * + * libxl may want to register more than one callback for any one fd; + * in that case: (i) each such registration will have at least one bit + * set in revents which is unique to that registration; (ii) if an + * event occurs which is relevant for multiple registrations the + * application's event system may call libxl_osevent_occurred_fd + * for one, some, or all of those registrations. + * + * If fd_modify is used, it is permitted for the application's event + * system to still make calls to libxl_osevent_occurred_fd for the + * "old" set of requested events; these will be safely ignored by + * libxl. + * + * libxl will remember the value stored in *for_app_registration_out + * (or *for_app_registration_update) by a successful call to + * register (or modify), and pass it to subsequent calls to modify + * or deregister. + * + * Note that the application must cope with a call from libxl to + * timeout_modify racing with its own call to + * libxl__osevent_occurred_timeout. libxl guarantees that + * timeout_modify will only be called with abs={0,0} but the + * application must still ensure that libxl's attempt to cause the + * timeout to occur immediately is safely ignored even the timeout is + * actually already in the process of occurring. + * + * timeout_deregister is not used because it forms part of a + * deprecated unsafe mode of use of the API. + * + * osevent_register_hooks may be called only once for each libxl_ctx. + * libxl may make calls to register/modify/deregister from within + * any libxl function (indeed, it will usually call register from + * register_event_hooks). Conversely, the application MUST NOT make + * the event occurrence calls (libxl_osevent_occurred_*) into libxl + * reentrantly from within libxl (for example, from within the + * register/modify functions). + * + * Lock hierarchy: the register/modify/deregister functions may be + * called with locks held. These locks (the "libxl internal locks") + * are inside the libxl_ctx. Therefore, if those register functions + * acquire any locks of their own ("caller register locks") outside + * libxl, to avoid deadlock one of the following must hold for each + * such caller register lock: + * (a) "acquire libxl internal locks before caller register lock": + * No libxl function may be called with the caller register + * lock held. + * (b) "acquire caller register lock before libxl internal locks": + * No libxl function may be called _without_ the caller + * register lock held. + * Of these we would normally recommend (a). + * + * The value *hooks is not copied and must outlast the libxl_ctx. + */ +void libxl_osevent_register_hooks(libxl_ctx *ctx, + const libxl_osevent_hooks *hooks, + void *user); + +/* It is NOT legal to call _occurred_ reentrantly within any libxl + * function. Specifically it is NOT legal to call it from within + * a register callback. Conversely, libxl MAY call register/deregister + * from within libxl_event_occurred_call_*. + */ + +void libxl_osevent_occurred_fd(libxl_ctx *ctx, void *for_libxl, + int fd, short events, short revents) + LIBXL_EXTERNAL_CALLERS_ONLY; + +/* Implicitly, on entry to this function the timeout has been + * deregistered. If _occurred_timeout is called, libxl will not + * call timeout_deregister; if it wants to requeue the timeout it + * will call timeout_register again. + */ +void libxl_osevent_occurred_timeout(libxl_ctx *ctx, void *for_libxl) + LIBXL_EXTERNAL_CALLERS_ONLY; + + +/*======================================================================*/ + +/* + * Subprocess handling. + * + * Unfortunately the POSIX interface makes this very awkward. + * + * There are two possible arrangements for collecting statuses from + * wait/waitpid. + * + * For naive programs: + * + * libxl will keep a SIGCHLD handler installed whenever it has an + * active (unreaped) child. It will reap all children with + * wait(); any children it does not recognise will be passed to + * the application via an optional callback (and will result in + * logged warnings if no callback is provided or the callback + * denies responsibility for the child). + * + * libxl may have children whenever: + * + * - libxl is performing an operation which can be made + * asynchronous; ie one taking a libxl_asyncop_how, even + * if NULL is passed indicating that the operation is + * synchronous; or + * + * - events of any kind are being generated, as requested + * by libxl_evenable_.... + * + * A multithreaded application which is naive in this sense may + * block SIGCHLD on some of its threads, but there must be at + * least one thread that has SIGCHLD unblocked. libxl will not + * modify the blocking flag for SIGCHLD (except that it may create + * internal service threads with all signals blocked). + * + * A naive program must only have at any one time only + * one libxl context which might have children. + * + * For programs which run their own children alongside libxl's: + * + * A program which does this must call libxl_childproc_setmode. + * There are three options: + * + * libxl_sigchld_owner_libxl: + * + * While any libxl operation which might use child processes + * is running, works like libxl_sigchld_owner_libxl_always; + * but, deinstalls the handler the rest of the time. + * + * In this mode, the application, while it uses any libxl + * operation which might create or use child processes (see + * above): + * - Must not have any child processes running. + * - Must not install a SIGCHLD handler. + * - Must not reap any children. + * + * This is the default (i.e. if setmode is not called, or 0 is + * passed for hooks). + * + * libxl_sigchld_owner_mainloop: + * + * The application must install a SIGCHLD handler and reap (at + * least) all of libxl's children and pass their exit status to + * libxl by calling libxl_childproc_exited. (If the application + * has multiple libxl ctx's, it must call libxl_childproc_exited + * on each ctx.) + * + * libxl_sigchld_owner_libxl_always: + * + * The application expects this libxl ctx to reap all of the + * process's children, and provides a callback to be notified of + * their exit statuses. The application must have only one + * libxl_ctx configured this way. + * + * libxl_sigchld_owner_libxl_always_selective_reap: + * + * The application expects to reap all of its own children + * synchronously, and does not use SIGCHLD. libxl is to install + * a SIGCHLD handler. The application may have multiple + * libxl_ctxs configured this way; in which case all of its ctxs + * must be so configured. + */ + + +typedef enum { + /* libxl owns SIGCHLD whenever it has a child, and reaps + * all children, including those not spawned by libxl. */ + libxl_sigchld_owner_libxl, + + /* Application promises to discover when SIGCHLD occurs and call + * libxl_childproc_exited or libxl_childproc_sigchld_occurred (but + * NOT from within a signal handler). libxl will not itself + * arrange to (un)block or catch SIGCHLD. */ + libxl_sigchld_owner_mainloop, + + /* libxl owns SIGCHLD all the time, and the application is + * relying on libxl's event loop for reaping its children too. */ + libxl_sigchld_owner_libxl_always, + + /* libxl owns SIGCHLD all the time, but it must only reap its own + * children. The application will reap its own children + * synchronously with waitpid, without the assistance of SIGCHLD. */ + libxl_sigchld_owner_libxl_always_selective_reap, +} libxl_sigchld_owner; + +typedef struct { + libxl_sigchld_owner chldowner; + + /* All of these are optional: */ + + /* Called by libxl instead of fork. Should behave exactly like + * fork, including setting errno etc. May NOT reenter into libxl. + * Application may use this to discover pids of libxl's children, + * for example. + */ + pid_t (*fork_replacement)(void *user); + + /* With libxl_sigchld_owner_libxl, called by libxl when it has + * reaped a pid. (Not permitted with _owner_mainloop.) + * + * Should return 0 if the child was recognised by the application + * (or if the application does not keep those kind of records), + * ERROR_UNKNOWN_CHILD if the application knows that the child is not + * the application's; if it returns another error code it is a + * disaster as described for libxl_event_register_callbacks. + * (libxl will report unexpected children to its error log.) + * + * If not supplied, the application is assumed not to start + * any children of its own. + * + * This function is NOT called from within the signal handler. + * Rather it will be called from inside a libxl's event handling + * code and thus only when libxl is running, for example from + * within libxl_event_wait. (libxl uses the self-pipe trick + * to implement this.) + * + * childproc_exited_callback may call back into libxl, but it + * is best to avoid making long-running libxl calls as that might + * stall the calling event loop while the nested operation + * completes. + */ + int (*reaped_callback)(pid_t, int status, void *user); +} libxl_childproc_hooks; + +/* hooks may be 0 in which is equivalent to &{ libxl_sigchld_owner_libxl, 0, 0 } + * + * May not be called when libxl might have any child processes, or the + * behaviour is undefined. So it is best to call this at + * initialisation. + * + * The value *hooks is not copied and must outlast the libxl_ctx. + */ +void libxl_childproc_setmode(libxl_ctx *ctx, const libxl_childproc_hooks *hooks, + void *user); + +/* + * This function is for an application which owns SIGCHLD and which + * reaps all of the process's children, and dispatches the exit status + * to the correct place inside the application. + * + * May be called only by an application which has called setmode with + * chldowner == libxl_sigchld_owner_mainloop. If pid was a process started + * by this instance of libxl, returns 0 after doing whatever + * processing is appropriate. Otherwise silently returns + * ERROR_UNKNOWN_CHILD. No other error returns are possible. + * + * May NOT be called from within a signal handler which might + * interrupt any libxl operation. The application will almost + * certainly need to use the self-pipe trick (or a working pselect or + * ppoll) to implement this. + */ +int libxl_childproc_reaped(libxl_ctx *ctx, pid_t, int status) + LIBXL_EXTERNAL_CALLERS_ONLY; + +/* + * This function is for an application which owns SIGCHLD but which + * doesn't keep track of all of its own children in a manner suitable + * for reaping all of them and then dispatching them. + * + * Such an the application must notify libxl, by calling this + * function, that a SIGCHLD occurred. libxl will then check all its + * children, reap any that are ready, and take any action necessary - + * but it will not reap anything else. + * + * May be called only by an application which has called setmode with + * chldowner == libxl_sigchld_owner_mainloop. + * + * May NOT be called from within a signal handler which might + * interrupt any libxl operation (just like libxl_childproc_reaped). + */ +void libxl_childproc_sigchld_occurred(libxl_ctx *ctx) + LIBXL_EXTERNAL_CALLERS_ONLY; + + +/* + * An application which initialises a libxl_ctx in a parent process + * and then forks a child which does not quickly exec, must + * instead libxl_postfork_child_noexec in the child. One call + * on any existing (or specially made) ctx is sufficient; after + * this all previously existing libxl_ctx's are invalidated and + * must not be used - or even freed. It is harmless to call this + * postfork function and then exec anyway. + * + * Until libxl_postfork_child_noexec has returned: + * - No other libxl calls may be made. + * - If any libxl ctx was configured handle the process's SIGCHLD, + * the child may not create further (grand)child processes, nor + * manipulate SIGCHLD. + * + * libxl_postfork_child_noexec may not reclaim all the resources + * associated with the libxl ctx. This includes but is not limited + * to: ordinary memory; files on disk and in /var/run; file + * descriptors; memory mapped into the process from domains being + * managed (grant maps); Xen event channels. Use of libxl in + * processes which fork long-lived children is not recommended for + * this reason. libxl_postfork_child_noexec is provided so that + * an application can make further libxl calls in a child which + * is going to exec or exit soon. + */ +void libxl_postfork_child_noexec(libxl_ctx *ctx); + + +#endif + +/* + * Local variables: + * mode: C + * c-basic-offset: 4 + * indent-tabs-mode: nil + * End: + */ |