Re: [libvirt] [PATCH 1/6] Introduce storage lifecycle event APIs

virConnectStoragePoolEventRegisterAny: Adds a callback to receive notifications of storage pool events occurring on a storage pool. Returns a positive integer identifier for the callback virConnectStoragePoolEventDeregisterAny: Removes an event callback virConnectStoragePoolEventGenericCallback: A generic storage pool event callback handler, for use with virStoragePoolEventRegisterAny(). VIR_STORAGE_POOL_EVENT_CALLBACK: Used to cast the event specific callback into the generic one for use for virConnectionStoragePoolEventRegisterAny() virStoragePoolEventID: An enumeration of supported eventIDs for virStoragePoolEventRegisterAny() virStoragePoolEventLifecycleType (VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE): emitting during storage pool lifecycle events virConnectStoragePoolEventLifecycleCallback: This callback occurs when pool is started, stopped or refreshed. Used when registering an event of type VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with virStoragePoolEvenTrgisterAny() --- include/libvirt/libvirt-storage.h | 94 +++++++++++++++++++++++++++++ src/datatypes.h | 13 ++++ src/driver-storage.h | 14 +++++ src/libvirt-storage.c | 122 ++++++++++++++++++++++++++++++++++++++ src/libvirt_public.syms | 7 +++ 5 files changed, 250 insertions(+) diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index db6f2b4..cfbdedf 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -377,5 +377,99 @@ int virStorageVolResize (virStorageVolPtr vol, int virStoragePoolIsActive(virStoragePoolPtr pool); int virStoragePoolIsPersistent(virStoragePoolPtr pool); +/** + * VIR_STORAGE_POOL_EVENT_CALLBACK: + * + * Used to cast the event specific callback into the generic one + * for use for virConnectStoragePoolEventRegisterAny() + */ +# define VIR_STORAGE_POOL_EVENT_CALLBACK(cb) ((virConnectStoragePoolEventGenericCallback)(cb)) +

+/** + * virStoragePoolEventID: + * + * An enumeration of supported eventId parameters for + * virConnectStoragePoolEventRegisterAny(). Each event id determines which + * signature of callback function will be used. + */ +typedef enum { + VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0, /* virConnectStoragePoolEventLifecycleCallback */ + +# ifdef VIR_ENUM_SENTINELS + VIR_STORAGE_POOL_EVENT_ID_LAST + /* + * 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. + */ +# endif +} virStoragePoolEventID; + +/** + * virConnectStoragePoolEventGenericCallback: + * @conn: the connection pointer + * @pool: the pool pointer + * @opaque: application specified data + * + * A generic storage pool event callback handler, for use with + * virConnectStoragePoolEventRegisterAny(). + * Spcific events usually have a customization with extra paramenters, + * often with @opaque being passed in a different parameter possition;

+ * use VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an + * appropriate handler. + */ +typedef void (*virConnectStoragePoolEventGenericCallback)(virConnectPtr conn, + virStoragePool pool,

+ void *opaque); + +/* Use VIR_STORAGE_POOL_EVENT_CALLBACK() to cast the 'cb' parameter */ +int virConnectStoragePoolEventRegisterAny(virConnectPtr conn, + virStoragePoolPtr pool, /* optional, to filter */ + int eventID, + virConnectStoragePoolEventGenericCallback cb, + void *opaque, + virFreeCallback freecb);

+ +int virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, + int callbackID); + +/** + * virStoragePoolEventLifecycleType: + * + * a virStoragePoolEventLifecycleType is emitted during storage pool + * lifecycle events + */ +typedef enum { + VIR_STORAGE_POOL_EVENT_DEFINED = 0, + VIR_STORAGE_POOL_EVENT_UNDEFINED = 1, + VIR_STORAGE_POOL_EVENT_STARTED = 2, + VIR_STORAGE_POOL_EVENT_STOPPED = 3, + VIR_STORAGE_POOL_EVENT_REFRESHED = 4, + +# ifdef VIR_ENUM_SENTINELS + VIR_STORAGE_POOL_EVENT_LAST +# endif +} virStoragePoolEventLifecycleType; + +/** + * virConnectStoragePoolEventLifecycleCallback: + * @conn: connection object + * @pool: pool on which the event occurred + * @event: The specific virStoragePoolEventLifeCycleType which occurred + * @detail: contains some details on the reason of the event. + * It will be 0 for the while.

+ * @opaque: application specified data + * + * This callback occurs when the pool is started, stopped or refreshed. + *

+ * The callback signature to use when registering for an event of type + * VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with + * virConnectStoragePoolEventRegisterAny() + */ +typedef void (*virConnectStoragePoolEventLifecycleCallback)(virConnectPtr conn, + virStoragePoolPtr pool, + int event, + int detail, + void *opaque); #endif /* __VIR_LIBVIRT_STORAGE_H__ */ diff --git a/src/datatypes.h b/src/datatypes.h index 8ccc7b0..638bd23 100644 --- a/src/datatypes.h +++ b/src/datatypes.h @@ -143,6 +143,19 @@ extern virClassPtr virAdmClientClass; } \ } while (0) +# define virCheckStoragePoolGoto(obj, label) \ + do { \ + virStoragePoolPtr _pool= (obj); \ + if (!virObjectIsClass(_pool, virStoragePoolClass) || \ + !virObjectIsClass(_pool->conn, virConnectClass)) { \ + virReportErrorHelper(VIR_FROM_STORAGE, \ + VIR_ERR_INVALID_STORAGE_POOL, \ + __FILE__, __FUNCTION__, __LINE__, \ + __FUNCTION__); \ + goto label; \ + } \ + } while (0) + # define virCheckStorageVolReturn(obj, retval) \ do { \ virStorageVolPtr _vol = (obj); \ diff --git a/src/driver-storage.h b/src/driver-storage.h index 0489647..70a1dcc 100644 --- a/src/driver-storage.h +++ b/src/driver-storage.h @@ -196,6 +196,18 @@ typedef int typedef int (*virDrvStoragePoolIsPersistent)(virStoragePoolPtr pool); +typedef int +(*virDrvConnectStoragePoolEventRegisterAny)(virConnectPtr conn, + virStoragePoolPtr pool, + int eventID, + virConnectStoragePoolEventGenericCallback cb, + void *opaque, + virFreeCallback freecb); + +typedef int +(*virDrvConnectStoragePoolEventDeregisterAny)(virConnectPtr conn, + int callbackID); + typedef struct _virStorageDriver virStorageDriver; @@ -215,6 +227,8 @@ struct _virStorageDriver { virDrvConnectListDefinedStoragePools connectListDefinedStoragePools; virDrvConnectListAllStoragePools connectListAllStoragePools; virDrvConnectFindStoragePoolSources connectFindStoragePoolSources; + virDrvConnectStoragePoolEventRegisterAny connectStoragePoolEventRegisterAny; + virDrvConnectStoragePoolEventDeregisterAny connectStoragePoolEventDeregisterAny; virDrvStoragePoolLookupByName storagePoolLookupByName; virDrvStoragePoolLookupByUUID storagePoolLookupByUUID; virDrvStoragePoolLookupByVolume storagePoolLookupByVolume; diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c index 1ce6745..33362ea 100644 --- a/src/libvirt-storage.c +++ b/src/libvirt-storage.c @@ -2124,3 +2124,125 @@ virStoragePoolIsPersistent(virStoragePoolPtr pool) virDispatchError(pool->conn); return -1; } + +/** + * virConnectStoragePoolEventRegisterAny: + * @conn: pointer to the connection + * @pool: pointer to the storage pool + * @eventID: the event type to receive + * @cb: callback to the function handling network 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 storage pool events + * occurring on a storage pool. This function requires that an event loop + * has been previously registered with virEventRegisterImpl() or + * virEventRegisterDefaultImpl(). + * + * If @pool is NULL, then events will be monitored for any storage pool. + * If @pool is non-NULL, then only the specific storage pool 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 necessary to use + * the VIR_STORAGE_POOL_EVENT_CALLBACK() macro to cast the supplied function pointer

+ * to match the signature of this method. + * + * The virStoragePoolPtr 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 storage pool object after the callback + * returns, it shall take a reference to it, by calling virStoragePoolRef(). + * The reference can be released once the object is no longer required + * by calling virStoragePoolFree(). + * + * 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 virConnectStoragePoolEventDeregisterAny() method. + * + * Returns a callback identifier on success, -1 on failure. + */ +int +virConnectStoragePoolEventRegisterAny(virConnectPtr conn, + virStoragePoolPtr pool, + int eventID, + virConnectStoragePoolEventGenericCallback cb, + void *opaque, + virFreeCallback freecb) +{ + VIR_DEBUG("conn=%p, eventID=%d, cb=%p, opaque=%p, freecb=%p", + conn, eventID, cb, opaque, freecb); +

+ virResetLastError(); + + virCheckConnectReturn(conn, -1); + if (pool) { + virCheckStoragePoolGoto(pool, error); + if (pool->conn != conn) { + virReportInvalidArg(pool, + _("storage pool'%s' in %s must match connection"),

+ pool->name, __FUNCTION__); + goto error; + } + } + virCheckNonNullArgGoto(cb, error); + virCheckNonNegativeArgGoto(eventID, error); + + if (eventID >= VIR_STORAGE_POOL_EVENT_ID_LAST) { + virReportInvalidArg(eventID, + _("eventID in %s must be less than %d"), + __FUNCTION__, VIR_STORAGE_POOL_EVENT_ID_LAST); + goto error; + } + + if (conn->storageDriver && conn->storageDriver->connectStoragePoolEventRegisterAny) {

+ int ret; + ret = conn->storageDriver->connectStoragePoolEventRegisterAny(conn, pool, + eventID, + cb, opaque, + freecb);

+ if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + +/** + * virConnectStoragePoolEventDeregisterAny: + * @conn: pointer to the connection + * @callbackID: the callback identifier + * + * Removes an event callback. The callbackID parameter should be the + * value obtained from a previous virConnectStoragePoolEventRegisterAny() method. + * + * Returns 0 on success, -1 on failure + */ +int +virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, + int callbackID) +{ + VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID); + + virResetLastError(); + + virCheckConnectReturn(conn, -1); + virCheckNonNegativeArgGoto(callbackID, error); + + if (conn->storageDriver && + conn->storageDriver->connectStoragePoolEventDeregisterAny) { + int ret; + ret = conn->storageDriver->connectStoragePoolEventDeregisterAny(conn, + callbackID); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index 1e920d6..f5898ee 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -732,4 +732,11 @@ LIBVIRT_1.3.3 { virDomainSetPerfEvents; } LIBVIRT_1.2.19; + +LIBVIRT_1.3.6 { + global: + virConnectStoragePoolEventRegisterAny; + virConnectStoragePoolEventDeregisterAny; +} LIBVIRT_1.3.3; + # .... define new API here using predicted next version number ....