While working on events, I found a number of minor issues; I'm hoisting these to the front rather than doing it piecemeal in the patches where I first noticed bad or missing documentation. * src/conf/object_event.c: Fix grammar, document all parameters of public functions; wrap some long lines. * src/conf/object_event.h: Likewise. * src/conf/network_event.c: Likewise. * src/conf/domain_event.c: Likewise (except for the large number of event creation functions). Signed-off-by: Eric Blake <eblake@redhat.com> --- src/conf/domain_event.c | 64 +++++++++++++++++++++++++-------------- src/conf/network_event.c | 26 +++++++++++----- src/conf/object_event.c | 78 +++++++++++++++++++++++++++++++++++++++++++----- src/conf/object_event.h | 7 +++-- 4 files changed, 134 insertions(+), 41 deletions(-) diff --git a/src/conf/domain_event.c b/src/conf/domain_event.c index e5f5796..8800568 100644 --- a/src/conf/domain_event.c +++ b/src/conf/domain_event.c @@ -1,7 +1,7 @@ /* * domain_event.c: domain event queue processing helpers * - * Copyright (C) 2010-2013 Red Hat, Inc. + * Copyright (C) 2010-2014 Red Hat, Inc. * Copyright (C) 2008 VirtualIron * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * @@ -70,7 +70,7 @@ virDomainEventDispatchDefaultFunc(virConnectPtr conn, struct _virDomainEvent { virObjectEvent parent; - /* Unused attribute to get virDomainEvent class being created */ + /* Unused attribute to allow for subclass creation */ bool dummy; }; typedef struct _virDomainEvent virDomainEvent; @@ -172,7 +172,8 @@ typedef struct _virDomainEventDeviceRemoved virDomainEventDeviceRemoved; typedef virDomainEventDeviceRemoved *virDomainEventDeviceRemovedPtr; -static int virDomainEventsOnceInit(void) +static int +virDomainEventsOnceInit(void) { if (!(virDomainEventClass = virClassNew(virClassForObjectEvent(), @@ -246,32 +247,37 @@ static int virDomainEventsOnceInit(void) VIR_ONCE_GLOBAL_INIT(virDomainEvents) -static void virDomainEventDispose(void *obj) +static void +virDomainEventDispose(void *obj) { virDomainEventPtr event = obj; VIR_DEBUG("obj=%p", event); } -static void virDomainEventLifecycleDispose(void *obj) +static void +virDomainEventLifecycleDispose(void *obj) { virDomainEventLifecyclePtr event = obj; VIR_DEBUG("obj=%p", event); } -static void virDomainEventRTCChangeDispose(void *obj) +static void +virDomainEventRTCChangeDispose(void *obj) { virDomainEventRTCChangePtr event = obj; VIR_DEBUG("obj=%p", event); } -static void virDomainEventWatchdogDispose(void *obj) +static void +virDomainEventWatchdogDispose(void *obj) { virDomainEventWatchdogPtr event = obj; VIR_DEBUG("obj=%p", event); } -static void virDomainEventIOErrorDispose(void *obj) +static void +virDomainEventIOErrorDispose(void *obj) { virDomainEventIOErrorPtr event = obj; VIR_DEBUG("obj=%p", event); @@ -281,7 +287,8 @@ static void virDomainEventIOErrorDispose(void *obj) VIR_FREE(event->reason); } -static void virDomainEventGraphicsDispose(void *obj) +static void +virDomainEventGraphicsDispose(void *obj) { virDomainEventGraphicsPtr event = obj; VIR_DEBUG("obj=%p", event); @@ -307,7 +314,8 @@ static void virDomainEventGraphicsDispose(void *obj) } } -static void virDomainEventBlockJobDispose(void *obj) +static void +virDomainEventBlockJobDispose(void *obj) { virDomainEventBlockJobPtr event = obj; VIR_DEBUG("obj=%p", event); @@ -315,7 +323,8 @@ static void virDomainEventBlockJobDispose(void *obj) VIR_FREE(event->path); } -static void virDomainEventDiskChangeDispose(void *obj) +static void +virDomainEventDiskChangeDispose(void *obj) { virDomainEventDiskChangePtr event = obj; VIR_DEBUG("obj=%p", event); @@ -325,7 +334,8 @@ static void virDomainEventDiskChangeDispose(void *obj) VIR_FREE(event->devAlias); } -static void virDomainEventTrayChangeDispose(void *obj) +static void +virDomainEventTrayChangeDispose(void *obj) { virDomainEventTrayChangePtr event = obj; VIR_DEBUG("obj=%p", event); @@ -333,13 +343,15 @@ static void virDomainEventTrayChangeDispose(void *obj) VIR_FREE(event->devAlias); } -static void virDomainEventBalloonChangeDispose(void *obj) +static void +virDomainEventBalloonChangeDispose(void *obj) { virDomainEventBalloonChangePtr event = obj; VIR_DEBUG("obj=%p", event); } -static void virDomainEventDeviceRemovedDispose(void *obj) +static void +virDomainEventDeviceRemovedDispose(void *obj) { virDomainEventDeviceRemovedPtr event = obj; VIR_DEBUG("obj=%p", event); @@ -354,7 +366,9 @@ static void virDomainEventDeviceRemovedDispose(void *obj) * @cbList: the list * @callback: the callback to remove * - * Internal function to remove a callback from a virObjectEventCallbackListPtr + * Internal function to remove a callback from a virObjectEventCallbackListPtr, + * when registered via the older virConnectDomainEventRegister with no + * callbackID */ static int virDomainEventCallbackListRemove(virConnectPtr conn, @@ -430,9 +444,11 @@ virDomainEventCallbackListMarkDelete(virConnectPtr conn, * @conn: pointer to the connection * @cbList: the list * @callback: the callback to add - * @opaque: opaque data tio pass to callback + * @opaque: opaque data to pass to @callback + * @freecb: callback to free @opaque * - * Internal function to add a callback from a virObjectEventCallbackListPtr + * Internal function to add a callback from a virObjectEventCallbackListPtr, + * when registered via the older virConnectDomainEventRegister. */ static int virDomainEventCallbackListAdd(virConnectPtr conn, @@ -1355,8 +1371,8 @@ cleanup: * virDomainEventStateRegister: * @conn: connection to associate with callback * @state: object event state - * @callback: function to remove from event - * @opaque: data blob to pass to callback + * @callback: the callback to add + * @opaque: data blob to pass to @callback * @freecb: callback to free @opaque * * Register the function @callback with connection @conn, @@ -1409,14 +1425,16 @@ cleanup: * virDomainEventStateRegisterID: * @conn: connection to associate with callback * @state: object event state + * @dom: optional domain for filtering the event * @eventID: ID of the event type to register for - * @cb: function to remove from event - * @opaque: data blob to pass to callback + * @cb: function to invoke when event fires + * @opaque: data blob to pass to @callback * @freecb: callback to free @opaque * @callbackID: filled with callback ID * - * Register the function @callbackID with connection @conn, - * from @state, for events of type @eventID. + * Register the function @cb with connection @conn, from @state, for + * events of type @eventID, and return the registration handle in + * @callbackID. * * Returns: the number of callbacks now registered, or -1 on error */ diff --git a/src/conf/network_event.c b/src/conf/network_event.c index 3819702..a192ffe 100644 --- a/src/conf/network_event.c +++ b/src/conf/network_event.c @@ -1,6 +1,7 @@ /* * network_event.c: network event queue processing helpers * + * Copyright (C) 2014 Red Hat, Inc. * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * * This library is free software; you can redistribute it and/or @@ -31,7 +32,7 @@ struct _virNetworkEvent { virObjectEvent parent; - /* Unused attribute to get virNetworkEvent class being created */ + /* Unused attribute to allow for subclass creation */ bool dummy; }; typedef struct _virNetworkEvent virNetworkEvent; @@ -71,7 +72,7 @@ virNetworkEventsOnceInit(void) VIR_ONCE_GLOBAL_INIT(virNetworkEvents) -void +static void virNetworkEventDispose(void *obj) { virNetworkEventPtr event = obj; @@ -79,7 +80,7 @@ virNetworkEventDispose(void *obj) } -void +static void virNetworkEventLifecycleDispose(void *obj) { virNetworkEventLifecyclePtr event = obj; @@ -126,13 +127,14 @@ cleanup: * @state: object event state * @net: network to filter on or NULL for all networks * @eventID: ID of the event type to register for - * @cb: function to add to event - * @opaque: data blob to pass to callback + * @cb: function to invoke when event occurs + * @opaque: data blob to pass to @callback * @freecb: callback to free @opaque * @callbackID: filled with callback ID * - * Register the function @callbackID with connection @conn, - * from @state, for events of type @eventID. + * Register the function @cb with connection @conn, from @state, for + * events of type @eventID, and return the registration handle in + * @callbackID. * * Returns: the number of callbacks now registered, or -1 on error */ @@ -161,6 +163,16 @@ virNetworkEventStateRegisterID(virConnectPtr conn, cb, opaque, freecb, callbackID); } + +/** + * virNetworkEventLifecycleNew: + * @name: name of the network object the event describes + * @uuid: uuid of the network object the event describes + * @type: type of lifecycle event + * @detail: more details about @type + * + * Create a new network lifecycle event. + */ virObjectEventPtr virNetworkEventLifecycleNew(const char *name, const unsigned char *uuid, diff --git a/src/conf/object_event.c b/src/conf/object_event.c index c86974b..eca6a10 100644 --- a/src/conf/object_event.c +++ b/src/conf/object_event.c @@ -1,7 +1,7 @@ /* * object_event.c: object event queue processing helpers * - * Copyright (C) 2010-2013 Red Hat, Inc. + * Copyright (C) 2010-2014 Red Hat, Inc. * Copyright (C) 2008 VirtualIron * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * @@ -43,7 +43,6 @@ struct _virObjectEventQueue { static virClassPtr virObjectEventClass; -static virClassPtr virObjectEventClass; static void virObjectEventDispose(void *obj); static int @@ -60,6 +59,12 @@ virObjectEventOnceInit(void) VIR_ONCE_GLOBAL_INIT(virObjectEvent) +/** + * virClassForObjectEvent: + * + * Return the class object to be used as a parent when creating an + * event subclass. + */ virClassPtr virClassForObjectEvent(void) { @@ -233,7 +238,8 @@ virObjectEventCallbackListPurgeMarked(virObjectEventCallbackListPtr cbList) * @klass: the base event class * @eventID: the event ID * @callback: the callback to add - * @opaque: opaque data tio pass to callback + * @opaque: opaque data to pass to @callback + * @freecb: callback to free @opaque * @callbackID: filled with callback ID * * Internal function to add a callback from a virObjectEventCallbackListPtr @@ -399,18 +405,33 @@ virObjectEventQueueNew(void) return ret; } + +/** + * virObjectEventStateLock: + * @state: the event state object + * + * Lock event state before calling functions from object_event_private.h. + */ void virObjectEventStateLock(virObjectEventStatePtr state) { virMutexLock(&state->lock); } + +/** + * virObjectEventStateUnlock: + * @state: the event state object + * + * Unlock event state after calling functions from object_event_private.h. + */ void virObjectEventStateUnlock(virObjectEventStatePtr state) { virMutexUnlock(&state->lock); } + /** * virObjectEventStateFree: * @list: virObjectEventStatePtr to free @@ -436,6 +457,16 @@ virObjectEventStateFree(virObjectEventStatePtr state) static void virObjectEventStateFlush(virObjectEventStatePtr state); + +/** + * virObjectEventTimer: + * @timer: id of the event loop timer + * @opaque: the event state object + * + * Register this function with the event state as its opaque data as + * the callback of a periodic timer on the event loop, in order to + * flush the callback queue. + */ void virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque) { @@ -444,8 +475,11 @@ virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque) virObjectEventStateFlush(state); } + /** * virObjectEventStateNew: + * + * Allocate a new event state object. */ virObjectEventStatePtr virObjectEventStateNew(void) @@ -477,6 +511,18 @@ error: return NULL; } + +/** + * virObjectEventNew: + * @klass: subclass of event to be created + * @dispatcher: callback for dispatching the particular subclass of event + * @eventID: id of the event + * @id: id of the object the event describes, or 0 + * @name: name of the object the event describes + * @uuid: uuid of the object the event describes + * + * Create a new event, with the information common to all events. + */ void * virObjectEventNew(virClassPtr klass, virObjectEventDispatchFunc dispatcher, @@ -514,6 +560,7 @@ virObjectEventNew(virClassPtr klass, return event; } + /** * virObjectEventQueuePush: * @evtQueue: the object event queue @@ -613,6 +660,16 @@ virObjectEventStateQueueDispatch(virObjectEventStatePtr state, queue->count = 0; } + +/** + * virObjectEventStateQueue: + * @state: the event state object + * @event: event to add to the queue + * + * Adds @event to the queue of events to be dispatched at the next + * safe moment. The caller should no longer use @event after this + * call. + */ void virObjectEventStateQueue(virObjectEventStatePtr state, virObjectEventPtr event) @@ -667,15 +724,19 @@ virObjectEventStateFlush(virObjectEventStatePtr state) * virObjectEventStateRegisterID: * @conn: connection to associate with callback * @state: domain event state + * @uuid: uuid of the object for event filtering + * @name: name of the object for event filtering + * @id: id of the object for event filtering, or 0 * @klass: the base event class * @eventID: ID of the event type to register for - * @cb: function to remove from event - * @opaque: data blob to pass to callback + * @cb: function to invoke when event occurs + * @opaque: data blob to pass to @callback * @freecb: callback to free @opaque * @callbackID: filled with callback ID * - * Register the function @callbackID with connection @conn, - * from @state, for events of type @eventID. + * Register the function @cb with connection @conn, from @state, for + * events of type @eventID, and return the registration handle in + * @callbackID. * * Returns: the number of callbacks now registered, or -1 on error */ @@ -746,7 +807,8 @@ virObjectEventStateDeregisterID(virConnectPtr conn, virObjectEventStateLock(state); if (state->isDispatching) ret = virObjectEventCallbackListMarkDeleteID(conn, - state->callbacks, callbackID); + state->callbacks, + callbackID); else ret = virObjectEventCallbackListRemoveID(conn, state->callbacks, callbackID); diff --git a/src/conf/object_event.h b/src/conf/object_event.h index 23ecb34..fa1281c 100644 --- a/src/conf/object_event.h +++ b/src/conf/object_event.h @@ -1,7 +1,7 @@ /* * object_event.h: object event queue processing helpers * - * Copyright (C) 2012 Red Hat, Inc. + * Copyright (C) 2012-2014 Red Hat, Inc. * Copyright (C) 2008 VirtualIron * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * @@ -47,7 +47,7 @@ void virObjectEventStateFree(virObjectEventStatePtr state); virObjectEventStatePtr virObjectEventStateNew(void); -/* +/** * virConnectObjectEventGenericCallback: * @conn: the connection pointer * @obj: the object pointer @@ -60,7 +60,8 @@ typedef void (*virConnectObjectEventGenericCallback)(virConnectPtr conn, void *obj, void *opaque); -# define VIR_OBJECT_EVENT_CALLBACK(cb) ((virConnectObjectEventGenericCallback)(cb)) +# define VIR_OBJECT_EVENT_CALLBACK(cb) \ + ((virConnectObjectEventGenericCallback)(cb)) void virObjectEventStateQueue(virObjectEventStatePtr state, -- 1.8.4.2