event: fix doc typos, and doc more public methods

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).
* src/libvirt_private.cyms (conf/object_event.h): Split...
(conf/network_event.h): ...to account for new file.

Signed-off-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Eric Blake 2014-01-02 07:16:49 -07:00
parent f06d55da7b
commit 6742fb0b10
5 changed files with 140 additions and 44 deletions

View File

@ -1,7 +1,7 @@
/* /*
* domain_event.c: domain event queue processing helpers * 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) 2008 VirtualIron
* Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
* *
@ -70,7 +70,7 @@ virDomainEventDispatchDefaultFunc(virConnectPtr conn,
struct _virDomainEvent { struct _virDomainEvent {
virObjectEvent parent; virObjectEvent parent;
/* Unused attribute to get virDomainEvent class being created */ /* Unused attribute to allow for subclass creation */
bool dummy; bool dummy;
}; };
typedef struct _virDomainEvent virDomainEvent; typedef struct _virDomainEvent virDomainEvent;
@ -172,7 +172,8 @@ typedef struct _virDomainEventDeviceRemoved virDomainEventDeviceRemoved;
typedef virDomainEventDeviceRemoved *virDomainEventDeviceRemovedPtr; typedef virDomainEventDeviceRemoved *virDomainEventDeviceRemovedPtr;
static int virDomainEventsOnceInit(void) static int
virDomainEventsOnceInit(void)
{ {
if (!(virDomainEventClass = if (!(virDomainEventClass =
virClassNew(virClassForObjectEvent(), virClassNew(virClassForObjectEvent(),
@ -246,32 +247,37 @@ static int virDomainEventsOnceInit(void)
VIR_ONCE_GLOBAL_INIT(virDomainEvents) VIR_ONCE_GLOBAL_INIT(virDomainEvents)
static void virDomainEventDispose(void *obj) static void
virDomainEventDispose(void *obj)
{ {
virDomainEventPtr event = obj; virDomainEventPtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
} }
static void virDomainEventLifecycleDispose(void *obj) static void
virDomainEventLifecycleDispose(void *obj)
{ {
virDomainEventLifecyclePtr event = obj; virDomainEventLifecyclePtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
} }
static void virDomainEventRTCChangeDispose(void *obj) static void
virDomainEventRTCChangeDispose(void *obj)
{ {
virDomainEventRTCChangePtr event = obj; virDomainEventRTCChangePtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
} }
static void virDomainEventWatchdogDispose(void *obj) static void
virDomainEventWatchdogDispose(void *obj)
{ {
virDomainEventWatchdogPtr event = obj; virDomainEventWatchdogPtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
} }
static void virDomainEventIOErrorDispose(void *obj) static void
virDomainEventIOErrorDispose(void *obj)
{ {
virDomainEventIOErrorPtr event = obj; virDomainEventIOErrorPtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
@ -281,7 +287,8 @@ static void virDomainEventIOErrorDispose(void *obj)
VIR_FREE(event->reason); VIR_FREE(event->reason);
} }
static void virDomainEventGraphicsDispose(void *obj) static void
virDomainEventGraphicsDispose(void *obj)
{ {
virDomainEventGraphicsPtr event = obj; virDomainEventGraphicsPtr event = obj;
VIR_DEBUG("obj=%p", event); 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; virDomainEventBlockJobPtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
@ -315,7 +323,8 @@ static void virDomainEventBlockJobDispose(void *obj)
VIR_FREE(event->path); VIR_FREE(event->path);
} }
static void virDomainEventDiskChangeDispose(void *obj) static void
virDomainEventDiskChangeDispose(void *obj)
{ {
virDomainEventDiskChangePtr event = obj; virDomainEventDiskChangePtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
@ -325,7 +334,8 @@ static void virDomainEventDiskChangeDispose(void *obj)
VIR_FREE(event->devAlias); VIR_FREE(event->devAlias);
} }
static void virDomainEventTrayChangeDispose(void *obj) static void
virDomainEventTrayChangeDispose(void *obj)
{ {
virDomainEventTrayChangePtr event = obj; virDomainEventTrayChangePtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
@ -333,13 +343,15 @@ static void virDomainEventTrayChangeDispose(void *obj)
VIR_FREE(event->devAlias); VIR_FREE(event->devAlias);
} }
static void virDomainEventBalloonChangeDispose(void *obj) static void
virDomainEventBalloonChangeDispose(void *obj)
{ {
virDomainEventBalloonChangePtr event = obj; virDomainEventBalloonChangePtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
} }
static void virDomainEventDeviceRemovedDispose(void *obj) static void
virDomainEventDeviceRemovedDispose(void *obj)
{ {
virDomainEventDeviceRemovedPtr event = obj; virDomainEventDeviceRemovedPtr event = obj;
VIR_DEBUG("obj=%p", event); VIR_DEBUG("obj=%p", event);
@ -354,7 +366,9 @@ static void virDomainEventDeviceRemovedDispose(void *obj)
* @cbList: the list * @cbList: the list
* @callback: the callback to remove * @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 static int
virDomainEventCallbackListRemove(virConnectPtr conn, virDomainEventCallbackListRemove(virConnectPtr conn,
@ -430,9 +444,11 @@ virDomainEventCallbackListMarkDelete(virConnectPtr conn,
* @conn: pointer to the connection * @conn: pointer to the connection
* @cbList: the list * @cbList: the list
* @callback: the callback to add * @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 static int
virDomainEventCallbackListAdd(virConnectPtr conn, virDomainEventCallbackListAdd(virConnectPtr conn,
@ -1355,8 +1371,8 @@ cleanup:
* virDomainEventStateRegister: * virDomainEventStateRegister:
* @conn: connection to associate with callback * @conn: connection to associate with callback
* @state: object event state * @state: object event state
* @callback: function to remove from event * @callback: the callback to add
* @opaque: data blob to pass to callback * @opaque: data blob to pass to @callback
* @freecb: callback to free @opaque * @freecb: callback to free @opaque
* *
* Register the function @callback with connection @conn, * Register the function @callback with connection @conn,
@ -1409,14 +1425,16 @@ cleanup:
* virDomainEventStateRegisterID: * virDomainEventStateRegisterID:
* @conn: connection to associate with callback * @conn: connection to associate with callback
* @state: object event state * @state: object event state
* @dom: optional domain for filtering the event
* @eventID: ID of the event type to register for * @eventID: ID of the event type to register for
* @cb: function to remove from event * @cb: function to invoke when event fires
* @opaque: data blob to pass to callback * @opaque: data blob to pass to @callback
* @freecb: callback to free @opaque * @freecb: callback to free @opaque
* @callbackID: filled with callback ID * @callbackID: filled with callback ID
* *
* Register the function @callbackID with connection @conn, * Register the function @cb with connection @conn, from @state, for
* from @state, for events of type @eventID. * events of type @eventID, and return the registration handle in
* @callbackID.
* *
* Returns: the number of callbacks now registered, or -1 on error * Returns: the number of callbacks now registered, or -1 on error
*/ */

View File

@ -1,6 +1,7 @@
/* /*
* network_event.c: network event queue processing helpers * network_event.c: network event queue processing helpers
* *
* Copyright (C) 2014 Red Hat, Inc.
* Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
* *
* This library is free software; you can redistribute it and/or * This library is free software; you can redistribute it and/or
@ -31,7 +32,7 @@
struct _virNetworkEvent { struct _virNetworkEvent {
virObjectEvent parent; virObjectEvent parent;
/* Unused attribute to get virNetworkEvent class being created */ /* Unused attribute to allow for subclass creation */
bool dummy; bool dummy;
}; };
typedef struct _virNetworkEvent virNetworkEvent; typedef struct _virNetworkEvent virNetworkEvent;
@ -71,7 +72,7 @@ virNetworkEventsOnceInit(void)
VIR_ONCE_GLOBAL_INIT(virNetworkEvents) VIR_ONCE_GLOBAL_INIT(virNetworkEvents)
void static void
virNetworkEventDispose(void *obj) virNetworkEventDispose(void *obj)
{ {
virNetworkEventPtr event = obj; virNetworkEventPtr event = obj;
@ -79,7 +80,7 @@ virNetworkEventDispose(void *obj)
} }
void static void
virNetworkEventLifecycleDispose(void *obj) virNetworkEventLifecycleDispose(void *obj)
{ {
virNetworkEventLifecyclePtr event = obj; virNetworkEventLifecyclePtr event = obj;
@ -126,13 +127,14 @@ cleanup:
* @state: object event state * @state: object event state
* @net: network to filter on or NULL for all networks * @net: network to filter on or NULL for all networks
* @eventID: ID of the event type to register for * @eventID: ID of the event type to register for
* @cb: function to add to event * @cb: function to invoke when event occurs
* @opaque: data blob to pass to callback * @opaque: data blob to pass to @callback
* @freecb: callback to free @opaque * @freecb: callback to free @opaque
* @callbackID: filled with callback ID * @callbackID: filled with callback ID
* *
* Register the function @callbackID with connection @conn, * Register the function @cb with connection @conn, from @state, for
* from @state, for events of type @eventID. * events of type @eventID, and return the registration handle in
* @callbackID.
* *
* Returns: the number of callbacks now registered, or -1 on error * Returns: the number of callbacks now registered, or -1 on error
*/ */
@ -161,6 +163,16 @@ virNetworkEventStateRegisterID(virConnectPtr conn,
cb, opaque, freecb, callbackID); 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 virObjectEventPtr
virNetworkEventLifecycleNew(const char *name, virNetworkEventLifecycleNew(const char *name,
const unsigned char *uuid, const unsigned char *uuid,

View File

@ -1,7 +1,7 @@
/* /*
* object_event.c: object event queue processing helpers * 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) 2008 VirtualIron
* Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
* *
@ -43,7 +43,6 @@ struct _virObjectEventQueue {
static virClassPtr virObjectEventClass; static virClassPtr virObjectEventClass;
static virClassPtr virObjectEventClass;
static void virObjectEventDispose(void *obj); static void virObjectEventDispose(void *obj);
static int static int
@ -60,6 +59,12 @@ virObjectEventOnceInit(void)
VIR_ONCE_GLOBAL_INIT(virObjectEvent) VIR_ONCE_GLOBAL_INIT(virObjectEvent)
/**
* virClassForObjectEvent:
*
* Return the class object to be used as a parent when creating an
* event subclass.
*/
virClassPtr virClassPtr
virClassForObjectEvent(void) virClassForObjectEvent(void)
{ {
@ -233,7 +238,8 @@ virObjectEventCallbackListPurgeMarked(virObjectEventCallbackListPtr cbList)
* @klass: the base event class * @klass: the base event class
* @eventID: the event ID * @eventID: the event ID
* @callback: the callback to add * @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 * @callbackID: filled with callback ID
* *
* Internal function to add a callback from a virObjectEventCallbackListPtr * Internal function to add a callback from a virObjectEventCallbackListPtr
@ -399,18 +405,33 @@ virObjectEventQueueNew(void)
return ret; return ret;
} }
/**
* virObjectEventStateLock:
* @state: the event state object
*
* Lock event state before calling functions from object_event_private.h.
*/
void void
virObjectEventStateLock(virObjectEventStatePtr state) virObjectEventStateLock(virObjectEventStatePtr state)
{ {
virMutexLock(&state->lock); virMutexLock(&state->lock);
} }
/**
* virObjectEventStateUnlock:
* @state: the event state object
*
* Unlock event state after calling functions from object_event_private.h.
*/
void void
virObjectEventStateUnlock(virObjectEventStatePtr state) virObjectEventStateUnlock(virObjectEventStatePtr state)
{ {
virMutexUnlock(&state->lock); virMutexUnlock(&state->lock);
} }
/** /**
* virObjectEventStateFree: * virObjectEventStateFree:
* @list: virObjectEventStatePtr to free * @list: virObjectEventStatePtr to free
@ -436,6 +457,16 @@ virObjectEventStateFree(virObjectEventStatePtr state)
static void virObjectEventStateFlush(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 void
virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque) virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque)
{ {
@ -444,8 +475,11 @@ virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque)
virObjectEventStateFlush(state); virObjectEventStateFlush(state);
} }
/** /**
* virObjectEventStateNew: * virObjectEventStateNew:
*
* Allocate a new event state object.
*/ */
virObjectEventStatePtr virObjectEventStatePtr
virObjectEventStateNew(void) virObjectEventStateNew(void)
@ -477,6 +511,18 @@ error:
return NULL; 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 * void *
virObjectEventNew(virClassPtr klass, virObjectEventNew(virClassPtr klass,
virObjectEventDispatchFunc dispatcher, virObjectEventDispatchFunc dispatcher,
@ -514,6 +560,7 @@ virObjectEventNew(virClassPtr klass,
return event; return event;
} }
/** /**
* virObjectEventQueuePush: * virObjectEventQueuePush:
* @evtQueue: the object event queue * @evtQueue: the object event queue
@ -560,7 +607,7 @@ virObjectEventDispatchMatchCallback(virObjectEventPtr event,
* will cause problems when a domain switches between * will cause problems when a domain switches between
* running & shutoff states & ignoring 'name' since * running & shutoff states & ignoring 'name' since
* Xen sometimes renames guests during migration, thus * Xen sometimes renames guests during migration, thus
* leaving 'uuid' as the only truly reliable ID we can use*/ * leaving 'uuid' as the only truly reliable ID we can use. */
if (memcmp(event->meta.uuid, cb->meta->uuid, VIR_UUID_BUFLEN) == 0) if (memcmp(event->meta.uuid, cb->meta->uuid, VIR_UUID_BUFLEN) == 0)
return 1; return 1;
@ -613,6 +660,16 @@ virObjectEventStateQueueDispatch(virObjectEventStatePtr state,
queue->count = 0; 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 void
virObjectEventStateQueue(virObjectEventStatePtr state, virObjectEventStateQueue(virObjectEventStatePtr state,
virObjectEventPtr event) virObjectEventPtr event)
@ -667,15 +724,19 @@ virObjectEventStateFlush(virObjectEventStatePtr state)
* virObjectEventStateRegisterID: * virObjectEventStateRegisterID:
* @conn: connection to associate with callback * @conn: connection to associate with callback
* @state: domain event state * @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 * @klass: the base event class
* @eventID: ID of the event type to register for * @eventID: ID of the event type to register for
* @cb: function to remove from event * @cb: function to invoke when event occurs
* @opaque: data blob to pass to callback * @opaque: data blob to pass to @callback
* @freecb: callback to free @opaque * @freecb: callback to free @opaque
* @callbackID: filled with callback ID * @callbackID: filled with callback ID
* *
* Register the function @callbackID with connection @conn, * Register the function @cb with connection @conn, from @state, for
* from @state, for events of type @eventID. * events of type @eventID, and return the registration handle in
* @callbackID.
* *
* Returns: the number of callbacks now registered, or -1 on error * Returns: the number of callbacks now registered, or -1 on error
*/ */
@ -746,7 +807,8 @@ virObjectEventStateDeregisterID(virConnectPtr conn,
virObjectEventStateLock(state); virObjectEventStateLock(state);
if (state->isDispatching) if (state->isDispatching)
ret = virObjectEventCallbackListMarkDeleteID(conn, ret = virObjectEventCallbackListMarkDeleteID(conn,
state->callbacks, callbackID); state->callbacks,
callbackID);
else else
ret = virObjectEventCallbackListRemoveID(conn, ret = virObjectEventCallbackListRemoveID(conn,
state->callbacks, callbackID); state->callbacks, callbackID);

View File

@ -1,7 +1,7 @@
/* /*
* object_event.h: object event queue processing helpers * 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) 2008 VirtualIron
* Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany. * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
* *
@ -47,7 +47,7 @@ void virObjectEventStateFree(virObjectEventStatePtr state);
virObjectEventStatePtr virObjectEventStatePtr
virObjectEventStateNew(void); virObjectEventStateNew(void);
/* /**
* virConnectObjectEventGenericCallback: * virConnectObjectEventGenericCallback:
* @conn: the connection pointer * @conn: the connection pointer
* @obj: the object pointer * @obj: the object pointer
@ -60,7 +60,8 @@ typedef void (*virConnectObjectEventGenericCallback)(virConnectPtr conn,
void *obj, void *obj,
void *opaque); void *opaque);
# define VIR_OBJECT_EVENT_CALLBACK(cb) ((virConnectObjectEventGenericCallback)(cb)) # define VIR_OBJECT_EVENT_CALLBACK(cb) \
((virConnectObjectEventGenericCallback)(cb))
void void
virObjectEventStateQueue(virObjectEventStatePtr state, virObjectEventStateQueue(virObjectEventStatePtr state,

View File

@ -534,6 +534,11 @@ virNetworkSetBridgeName;
virPortGroupFindByName; virPortGroupFindByName;
# conf/network_event.h
virNetworkEventLifecycleNew;
virNetworkEventStateRegisterID;
# conf/node_device_conf.h # conf/node_device_conf.h
virNodeDevCapsDefFree; virNodeDevCapsDefFree;
virNodeDevCapTypeFromString; virNodeDevCapTypeFromString;
@ -624,8 +629,6 @@ virNWFilterVarValueGetSimple;
# conf/object_event.h # conf/object_event.h
virNetworkEventLifecycleNew;
virNetworkEventStateRegisterID;
virObjectEventStateDeregisterID; virObjectEventStateDeregisterID;
virObjectEventStateEventID; virObjectEventStateEventID;
virObjectEventStateFree; virObjectEventStateFree;