[libvirt] [PATCH 1/2] event: fix doc typos, and doc more public methods
Eric Blake
eblake at redhat.com
Thu Jan 2 16:32:47 UTC 2014
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 at 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
More information about the libvir-list
mailing list