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

Registers a default event implementation based on the poll() system call. This is a generic implementation that can be used by any client application which does not have a need to integrate with an external event loop impl.

For proper event handling, it is important that the event implementation is registered before a connection to the Hypervisor is opened.

Once registered, the application has to invoke virEventRunDefaultImpl() in a loop to process events. Failure to do so may result in connections being closed unexpectedly as a result of keepalive timeout. The default event loop fully supports handle and timeout events, but only wakes up on events registered by libvirt API calls such as virEventAddHandle() or virConnectDomainEventRegisterAny().

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.

Once registered, the event loop implementation cannot be changed, and must be run continuously. Note that callbacks may remain registered for a short time even after calling virConnectClose on all open connections, so it is not safe to stop running the event loop immediately after closing the connection.

Run one iteration of the event loop. Applications will generally want to have a thread which invokes this method in an infinite loop. Furthermore, it is wise to set up a pipe-to-self handler (via virEventAddHandle()) or a timeout (via virEventAddTimeout()) before calling this function, as it will block forever if there are no registered events.