libvirt-event

libvirt-event - APIs for management of events

Provides APIs for the management of events

Author(s): Daniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see <http://www.gnu.org/licenses/>.

Synopsis

typedef enum virEventHandleType;
int	virEventAddHandle		(int fd, 
int events,
virEventHandleCallback cb,
void * opaque,
virFreeCallback ff); typedef int virEventAddHandleFunc (int fd,
int event,
virEventHandleCallback cb,
void * opaque,
virFreeCallback ff); int virEventAddTimeout (int timeout,
virEventTimeoutCallback cb,
void * opaque,
virFreeCallback ff); typedef int virEventAddTimeoutFunc (int timeout,
virEventTimeoutCallback cb,
void * opaque,
virFreeCallback ff); typedef void virEventHandleCallback (int watch,
int fd,
int events,
void * opaque); int virEventRegisterDefaultImpl (void); void virEventRegisterImpl (virEventAddHandleFunc addHandle,
virEventUpdateHandleFunc updateHandle,
virEventRemoveHandleFunc removeHandle,
virEventAddTimeoutFunc addTimeout,
virEventUpdateTimeoutFunc updateTimeout,
virEventRemoveTimeoutFunc removeTimeout); int virEventRemoveHandle (int watch); typedef int virEventRemoveHandleFunc (int watch); int virEventRemoveTimeout (int timer); typedef int virEventRemoveTimeoutFunc (int timer); int virEventRunDefaultImpl (void); typedef void virEventTimeoutCallback (int timer,
void * opaque); void virEventUpdateHandle (int watch,
int events); typedef void virEventUpdateHandleFunc (int watch,
int event); void virEventUpdateTimeout (int timer,
int timeout); typedef void virEventUpdateTimeoutFunc (int timer,
int timeout);

Description

Details


Function type virEventAddHandleFunc

int	virEventAddHandleFunc		(int fd, 
int event,
virEventHandleCallback cb,
void * opaque,
virFreeCallback ff)

Part of the EventImpl, this callback adds a file handle callback to listen for specific events. The same file handle can be registered multiple times provided the requested event sets are non-overlapping If the opaque user data requires free'ing when the handle is unregistered, then a 2nd callback can be supplied for this purpose. This callback needs to be invoked from a clean stack. If 'ff' callbacks are invoked directly from the virEventRemoveHandleFunc they will likely deadlock in libvirt.

fd:file descriptor to listen on
event:bitset of events on which to fire the callback
cb:the callback to be called when an event occurrs
opaque:user data to pass to the callback
ff:the callback invoked to free opaque data blob
Returns:-1 if the file handle cannot be registered, otherwise a handle watch number to be used for updating and unregistering for events

Function type virEventAddTimeoutFunc

int	virEventAddTimeoutFunc		(int timeout, 
virEventTimeoutCallback cb,
void * opaque,
virFreeCallback ff)

Part of the EventImpl, this user-defined callback handles adding an event timeout. If the opaque user data requires free'ing when the handle is unregistered, then a 2nd callback can be supplied for this purpose.

timeout:The timeout to monitor
cb:the callback to call when timeout has expired
opaque:user data to pass to the callback
ff:the callback invoked to free opaque data blob
Returns:a timer value







virEventAddHandle ()

int	virEventAddHandle		(int fd, 
int events,
virEventHandleCallback cb,
void * opaque,
virFreeCallback ff)

Register a callback for monitoring file handle events. This function requires that an event loop has previously been registered with virEventRegisterImpl() or virEventRegisterDefaultImpl().

fd:file handle to monitor for events
events:bitset of events to watch from virEventHandleType constants
cb:callback to invoke when an event occurs
opaque:user data to pass to callback
ff:callback to free opaque when handle is removed
Returns:-1 if the file handle cannot be registered, otherwise a handle watch number to be used for updating and unregistering for events.

virEventAddTimeout ()

int	virEventAddTimeout		(int timeout, 
virEventTimeoutCallback cb,
void * opaque,
virFreeCallback ff)

Register a callback for a timer event. This function requires that an event loop has previously been registered with virEventRegisterImpl() or virEventRegisterDefaultImpl(). Setting @timeout to -1 will disable the timer. Setting @timeout to zero will cause it to fire on every event loop iteration.

timeout:time between events in milliseconds
cb:callback to invoke when an event occurs
opaque:user data to pass to callback
ff:callback to free opaque when timeout is removed
Returns:-1 if the timer cannot be registered, a positive integer timer id upon success.


virEventRegisterImpl ()

void	virEventRegisterImpl		(virEventAddHandleFunc addHandle, 
virEventUpdateHandleFunc updateHandle,
virEventRemoveHandleFunc removeHandle,
virEventAddTimeoutFunc addTimeout,
virEventUpdateTimeoutFunc updateTimeout,
virEventRemoveTimeoutFunc removeTimeout)

Registers an event implementation, to allow integration with an external event loop. Applications would use this to integrate with the libglib2 event loop, or libevent or the QT event loop. For proper event handling, it is important that the event implementation is registered before a connection to the Hypervisor is opened. Use of the virEventAddHandle() and similar APIs require that the corresponding handler is registered. Use of the virConnectDomainEventRegisterAny() and similar APIs requires that the three timeout handlers are registered. Likewise, the three timeout handlers must be registered if the remote server has been configured to send keepalive messages, or if the client intends to call virConnectSetKeepAlive(), to avoid either side from unexpectedly closing the connection due to inactivity. If an application does not need to integrate with an existing event loop implementation, then the virEventRegisterDefaultImpl() method can be used to setup the generic libvirt implementation.

addHandle:the callback to add fd handles
updateHandle:the callback to update fd handles
removeHandle:the callback to remove fd handles
addTimeout:the callback to add a timeout
updateTimeout:the callback to update a timeout
removeTimeout:the callback to remove a timeout