[libvirt] [PATCH 01/13] Introduce a new public API for domain events
Daniel P. Berrange
berrange at redhat.com
Fri Mar 19 15:38:49 UTC 2010
The current API for domain events has a number of problems
- Only allows for domain lifecycle change events
- Does not allow the same callback to be registered multiple times
- Does not allow filtering of events to a specific domain
This introduces a new more general purpose domain events API
typedef enum {
VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback */
...more events later..
}
int virConnectDomainEventRegisterAny(virConnectPtr conn,
virDomainPtr dom, /* Optional, to filter */
int eventID,
virConnectDomainEventGenericCallback cb,
void *opaque,
virFreeCallback freecb);
int virConnectDomainEventDeregisterAny(virConnectPtr conn,
int callbackID);
Since different event types can received different data in the callback,
the API is defined with a generic callback. Specific events will each
have a custom signature for their callback. Thus when registering an
event it is neccessary to cast the callback to the generic signature
eg
int myDomainEventCallback(virConnectPtr conn,
virDomainPtr dom,
int event,
int detail,
void *opaque)
{
...
}
virConnectDomainEventRegisterAny(conn, NULL,
VIR_DOMAIN_EVENT_ID_LIFECYCLE,
VIR_DOMAIN_EVENT_CALLBACK(myDomainEventCallback)
NULL, NULL);
The VIR_DOMAIN_EVENT_CALLBACK() macro simply does a "bad" cast
to the generic signature
* include/libvirt/libvirt.h.in: Define new APIs for registering
domain events
* src/driver.h: Internal driver entry points for new events APIs
* src/libvirt.c: Wire up public API to driver API for events APIs
* src/libvirt_public.syms: Export new APIs
* src/esx/esx_driver.c, src/lxc/lxc_driver.c, src/opennebula/one_driver.c,
src/openvz/openvz_driver.c, src/phyp/phyp_driver.c,
src/qemu/qemu_driver.c, src/remote/remote_driver.c,
src/test/test_driver.c, src/uml/uml_driver.c,
src/vbox/vbox_tmpl.c, src/xen/xen_driver.c,
src/xenapi/xenapi_driver.c: Stub out new API entries
---
include/libvirt/libvirt.h.in | 34 +++++++++++
src/driver.h | 14 +++++
src/esx/esx_driver.c | 2 +
src/libvirt.c | 133 ++++++++++++++++++++++++++++++++++++++++--
src/libvirt_public.syms | 6 ++
src/lxc/lxc_driver.c | 2 +
src/opennebula/one_driver.c | 2 +
src/openvz/openvz_driver.c | 2 +
src/phyp/phyp_driver.c | 2 +
src/qemu/qemu_driver.c | 2 +
src/remote/remote_driver.c | 2 +
src/test/test_driver.c | 2 +
src/uml/uml_driver.c | 2 +
src/vbox/vbox_tmpl.c | 2 +
src/xen/xen_driver.c | 2 +
src/xenapi/xenapi_driver.c | 2 +
16 files changed, 206 insertions(+), 5 deletions(-)
diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index 0d1b5b5..62a51ea 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -1837,6 +1837,40 @@ int virDomainGetJobInfo(virDomainPtr dom,
int virDomainAbortJob(virDomainPtr dom);
+/* A generic callback definition. Specific events usually have a customization
+ * with extra parameters */
+typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
+ virDomainPtr dom,
+ void *opaque);
+
+/* Use this to cast the event specific callback into the generic one
+ * for use for virDomainEventRegister */
+#define VIR_DOMAIN_EVENT_CALLBACK(cb) ((virConnectDomainEventGenericCallback)(cb))
+
+
+typedef enum {
+ VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback */
+
+ /*
+ * NB: this enum value will increase over time as new events are
+ * added to the libvirt API. It reflects the last event ID supported
+ * by this version of the libvirt API.
+ */
+ VIR_DOMAIN_EVENT_ID_LAST
+} virDomainEventID;
+
+
+/* Use VIR_DOMAIN_EVENT_CALLBACK() to cast the 'cb' parameter */
+int virConnectDomainEventRegisterAny(virConnectPtr conn,
+ virDomainPtr dom, /* Optional, to filter */
+ int eventID,
+ virConnectDomainEventGenericCallback cb,
+ void *opaque,
+ virFreeCallback freecb);
+
+int virConnectDomainEventDeregisterAny(virConnectPtr conn,
+ int callbackID);
+
#ifdef __cplusplus
}
#endif
diff --git a/src/driver.h b/src/driver.h
index a64bba0..805b2b1 100644
--- a/src/driver.h
+++ b/src/driver.h
@@ -381,6 +381,18 @@ typedef int
typedef int
(*virDrvDomainAbortJob)(virDomainPtr domain);
+typedef int
+ (*virDrvDomainEventRegisterAny)(virConnectPtr conn,
+ virDomainPtr dom,
+ int eventID,
+ virConnectDomainEventGenericCallback cb,
+ void *opaque,
+ virFreeCallback freecb);
+
+typedef int
+ (*virDrvDomainEventDeregisterAny)(virConnectPtr conn,
+ int callbackID);
+
/**
* _virDriver:
*
@@ -474,6 +486,8 @@ struct _virDriver {
virDrvCPUBaseline cpuBaseline;
virDrvDomainGetJobInfo domainGetJobInfo;
virDrvDomainAbortJob domainAbortJob;
+ virDrvDomainEventRegisterAny domainEventRegisterAny;
+ virDrvDomainEventDeregisterAny domainEventDeregisterAny;
};
typedef int
diff --git a/src/esx/esx_driver.c b/src/esx/esx_driver.c
index ed2cbf7..f8b57b1 100644
--- a/src/esx/esx_driver.c
+++ b/src/esx/esx_driver.c
@@ -3411,6 +3411,8 @@ static virDriver esxDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
diff --git a/src/libvirt.c b/src/libvirt.c
index 1d9b878..6aabb57 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -9291,8 +9291,12 @@ error:
* @opaque: opaque data to pass on to the callback
* @freecb: optional function to deallocate opaque when not used anymore
*
- * Adds a Domain Event Callback.
- * Registering for a domain callback will enable delivery of the events
+ * Adds a callback to receive notifications of domain lifecycle events
+ * occurring on a connection
+ *
+ * Use of this method is no longer recommended. Instead applications
+ * should try virConnectDomainEventRegisterAny which has a more flexible
+ * API contract
*
* The virDomainPtr object handle passed into the callback upon delivery
* of an event is only valid for the duration of execution of the callback.
@@ -9341,9 +9345,12 @@ error:
* @conn: pointer to the connection
* @cb: callback to the function handling domain events
*
- * Removes a Domain Event Callback.
- * De-registering for a domain callback will disable
- * delivery of this event type
+ * Removes a callback previously registered with the virConnectDomainEventRegister
+ * funtion.
+ *
+ * Use of this method is no longer recommended. Instead applications
+ * should try virConnectDomainEventUnregisterAny which has a more flexible
+ * API contract
*
* Returns 0 on success, -1 on failure
*/
@@ -11265,3 +11272,119 @@ error:
virDispatchError(conn);
return -1;
}
+
+
+/**
+ * virConnectDomainEventRegister:
+ * @conn: pointer to the connection
+ * @dom: pointer to the domain
+ * @eventID: the event type to receive
+ * @cb: callback to the function handling domain events
+ * @opaque: opaque data to pass on to the callback
+ * @freecb: optional function to deallocate opaque when not used anymore
+ *
+ * Adds a callback to receive notifications of arbitrary domain events
+ * occurring on a domain.
+ *
+ * If dom is NULL, then events will be monitored for any domain. If dom
+ * is non-NULL, then only the specific domain will be monitored
+ *
+ * Most types of event have a callback providing a custom set of parameters
+ * for the event. When registering an event, it is thus neccessary to use
+ * the VIR_DOMAIN_EVENT_CALLBACK() macro to cast the supplied function pointer
+ * to match the signature of this method.
+ *
+ * The virDomainPtr object handle passed into the callback upon delivery
+ * of an event is only valid for the duration of execution of the callback.
+ * If the callback wishes to keep the domain object after the callback
+ * returns, it shall take a reference to it, by calling virDomainRef.
+ * The reference can be released once the object is no longer required
+ * by calling virDomainFree.
+ *
+ * The return value from this method is a positive integer identifier
+ * for the callback. To unregister a callback, this callback ID should
+ * be passed to the virDomainEventUnregisterAny method
+ *
+ * Returns a callback identifier on success, -1 on failure
+ */
+int
+virConnectDomainEventRegisterAny(virConnectPtr conn,
+ virDomainPtr dom,
+ int eventID,
+ virConnectDomainEventGenericCallback cb,
+ void *opaque,
+ virFreeCallback freecb)
+{
+ DEBUG("conn=%p dom=%p, eventID=%d, cb=%p, opaque=%p, freecb=%p", conn, dom, eventID, cb, opaque, freecb);
+ virResetLastError();
+
+ if (!VIR_IS_CONNECT(conn)) {
+ virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
+ virDispatchError(NULL);
+ return (-1);
+ }
+ if (dom != NULL &&
+ !(VIR_IS_CONNECTED_DOMAIN(dom) && dom->conn == conn)) {
+ virLibConnError(conn, VIR_ERR_INVALID_CONN, __FUNCTION__);
+ virDispatchError(conn);
+ return (-1);
+ }
+ if (eventID < 0 || eventID >= VIR_DOMAIN_EVENT_ID_LAST || cb == NULL) {
+ virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
+ goto error;
+ }
+
+ if ((conn->driver) && (conn->driver->domainEventRegisterAny)) {
+ int ret;
+ ret = conn->driver->domainEventRegisterAny(conn, dom, eventID, cb, opaque, freecb);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virLibConnError(conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
+error:
+ virDispatchError(conn);
+ return -1;
+}
+
+/**
+ * virDomainEventUnregister:
+ * @conn: pointer to the connection
+ * @callbackID: the callback identifier
+ *
+ * Removes an event callback. The callbackID parameter should be the
+ * vaule obtained from a previous virDomainEventRegisterAny method.
+ *
+ * Returns 0 on success, -1 on failure
+ */
+int
+virConnectDomainEventDeregisterAny(virConnectPtr conn,
+ int callbackID)
+{
+ DEBUG("conn=%p, callbackID=%d", conn, callbackID);
+
+ virResetLastError();
+
+ if (!VIR_IS_CONNECT(conn)) {
+ virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
+ virDispatchError(NULL);
+ return (-1);
+ }
+ if (callbackID < 0) {
+ virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
+ goto error;
+ }
+ if ((conn->driver) && (conn->driver->domainEventDeregisterAny)) {
+ int ret;
+ ret = conn->driver->domainEventDeregisterAny(conn, callbackID);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virLibConnError(conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
+error:
+ virDispatchError(conn);
+ return -1;
+}
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 64e7505..b1689ee 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -358,4 +358,10 @@ LIBVIRT_0.7.7 {
virDomainAbortJob;
} LIBVIRT_0.7.5;
+LIBVIRT_0.7.8 {
+ global:
+ virConnectDomainEventRegisterAny;
+ virConnectDomainEventDeregisterAny;
+} LIBVIRT_0.7.7;
+
# .... define new API here using predicted next version number ....
diff --git a/src/lxc/lxc_driver.c b/src/lxc/lxc_driver.c
index 35c8659..41d66bf 100644
--- a/src/lxc/lxc_driver.c
+++ b/src/lxc/lxc_driver.c
@@ -2453,6 +2453,8 @@ static virDriver lxcDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
static virStateDriver lxcStateDriver = {
diff --git a/src/opennebula/one_driver.c b/src/opennebula/one_driver.c
index 9fc0ada..a3f7c6c 100644
--- a/src/opennebula/one_driver.c
+++ b/src/opennebula/one_driver.c
@@ -788,6 +788,8 @@ static virDriver oneDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
static virStateDriver oneStateDriver = {
diff --git a/src/openvz/openvz_driver.c b/src/openvz/openvz_driver.c
index b7bc43b..49f3347 100644
--- a/src/openvz/openvz_driver.c
+++ b/src/openvz/openvz_driver.c
@@ -1540,6 +1540,8 @@ static virDriver openvzDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
int openvzRegister(void) {
diff --git a/src/phyp/phyp_driver.c b/src/phyp/phyp_driver.c
index ae210c3..7783182 100644
--- a/src/phyp/phyp_driver.c
+++ b/src/phyp/phyp_driver.c
@@ -1647,6 +1647,8 @@ virDriver phypDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
int
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index 67d9ade..81b4f36 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -9597,6 +9597,8 @@ static virDriver qemuDriver = {
qemuCPUBaseline, /* cpuBaseline */
qemuDomainGetJobInfo, /* domainGetJobInfo */
qemuDomainAbortJob, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
diff --git a/src/remote/remote_driver.c b/src/remote/remote_driver.c
index 11513bd..7013a05 100644
--- a/src/remote/remote_driver.c
+++ b/src/remote/remote_driver.c
@@ -9126,6 +9126,8 @@ static virDriver remote_driver = {
remoteCPUBaseline, /* cpuBaseline */
remoteDomainGetJobInfo, /* domainGetJobInfo */
remoteDomainAbortJob, /* domainFinishJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
static virNetworkDriver network_driver = {
diff --git a/src/test/test_driver.c b/src/test/test_driver.c
index 7960812..d58086e 100644
--- a/src/test/test_driver.c
+++ b/src/test/test_driver.c
@@ -5245,6 +5245,8 @@ static virDriver testDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
static virNetworkDriver testNetworkDriver = {
diff --git a/src/uml/uml_driver.c b/src/uml/uml_driver.c
index eec239f..63c2e98 100644
--- a/src/uml/uml_driver.c
+++ b/src/uml/uml_driver.c
@@ -1932,6 +1932,8 @@ static virDriver umlDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
diff --git a/src/vbox/vbox_tmpl.c b/src/vbox/vbox_tmpl.c
index b808910..b540f61 100644
--- a/src/vbox/vbox_tmpl.c
+++ b/src/vbox/vbox_tmpl.c
@@ -7066,6 +7066,8 @@ virDriver NAME(Driver) = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
virNetworkDriver NAME(NetworkDriver) = {
diff --git a/src/xen/xen_driver.c b/src/xen/xen_driver.c
index 5b9649c..9839858 100644
--- a/src/xen/xen_driver.c
+++ b/src/xen/xen_driver.c
@@ -1906,6 +1906,8 @@ static virDriver xenUnifiedDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
/**
diff --git a/src/xenapi/xenapi_driver.c b/src/xenapi/xenapi_driver.c
index a33d791..41908ee 100644
--- a/src/xenapi/xenapi_driver.c
+++ b/src/xenapi/xenapi_driver.c
@@ -1747,6 +1747,8 @@ static virDriver xenapiDriver = {
NULL, /* cpuBaseline */
NULL, /* domainGetJobInfo */
NULL, /* domainAbortJob */
+ NULL, /* domainEventRegisterAny */
+ NULL, /* domainEventDeregisterAny */
};
/**
--
1.6.6.1
More information about the libvir-list
mailing list