[libvirt] PATCH: Pass a callback for freeing opaque data when registering handle/timer events
Daniel Veillard
veillard at redhat.com
Wed Nov 19 13:21:40 UTC 2008
On Mon, Nov 17, 2008 at 05:02:40PM +0000, Daniel P. Berrange wrote:
> When registering for a file descriptor event, or timer events, the event
> callback has an associated 'void *opaque' data blob. When removing a
> registered event, the removal may be done asynchronously to allow safe
> removal from within a callback. This means that it is not safe for the
> application to assume they can free the 'void *opaque' data immediately
> after calling virEventRemoveHandle/Timer. So, we extend the AddHandle/Timer
> method to allow a 2nd callback to be provided. This callback is used to
> free the 'void *opaque' data at the appropriate (safe) point in time.
okay, it makes more sense to provide the API framework on how to free
the data
> diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h
> --- a/include/libvirt/libvirt.h
> +++ b/include/libvirt/libvirt.h
> @@ -1132,21 +1132,39 @@ typedef void (*virEventHandleCallback)(i
> typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque);
>
> /**
> + * virEventHandleFreeFunc:
> + *
> + * @opaque: user data to be free'd
> + *
> + * Callback invoked when memory associated with a file handle
> + * watch is being freed. Will be passed a pointer to the application's
> + * opaque data blob.
> + */
> +typedef void (*virEventHandleFreeFunc)(void *opaque);
> +
> +/**
> * virEventAddHandleFunc:
> * @fd: file descriptor to listen on
> * @event: bitset of events on which to fire the callback
> - * @cb: the callback to be called
> + * @cb: the callback to be called when an event occurrs
> + * @ff: the callback invoked to free opaque data blob
> * @opaque: user data to pass to the callback
> *
> * 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.
> + *
> * Returns a handle watch number to be used for updating
> * and unregistering for events
> */
> typedef int (*virEventAddHandleFunc)(int fd, int event,
> - virEventHandleCallback cb, void *opaque);
> + virEventHandleCallback cb,
> + virEventHandleFreeFunc ff,
> + void *opaque);
>
> /**
> * virEventUpdateHandleFunc:
> @@ -1163,7 +1181,11 @@ typedef void (*virEventUpdateHandleFunc)
> * @watch: file descriptor watch to stop listening on
> *
> * Part of the EventImpl, this user-provided callback is notified when
> - * an fd is no longer being listened on
> + * an fd is no longer being listened on.
> + *
> + * If a virEventHandleFreeFunc was supplied when the handle was
> + * registered, it will be invoked some time during, or after this
> + * function call, when it is safe to release the user data.
> */
> typedef int (*virEventRemoveHandleFunc)(int watch);
>
> @@ -1178,17 +1200,35 @@ typedef void (*virEventTimeoutCallback)(
> typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
>
> /**
> + * virEventTimeoutFreeFunc:
> + *
> + * @opaque: user data to be free'd
> + *
> + * Callback invoked when memory associated with a timer
> + * is being freed. Will be passed a pointer to the application's
> + * opaque data blob.
> + */
> +typedef void (*virEventTimeoutFreeFunc)(void *opaque);
> +
> +/**
> * virEventAddTimeoutFunc:
> * @timeout: The timeout to monitor
> * @cb: the callback to call when timeout has expired
> + * @ff: the callback invoked to free opaque data blob
> * @opaque: user data to pass to the callback
> *
> * 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.
> + *
> * Returns a timer value
> */
> -typedef int (*virEventAddTimeoutFunc)(int timeout, virEventTimeoutCallback cb,
> +typedef int (*virEventAddTimeoutFunc)(int timeout,
> + virEventTimeoutCallback cb,
> + virEventTimeoutFreeFunc ff,
> void *opaque);
>
> /**
> @@ -1207,6 +1247,10 @@ typedef void (*virEventUpdateTimeoutFunc
> *
> * Part of the EventImpl, this user-defined callback removes a timer
> *
> + * If a virEventTimeoutFreeFunc was supplied when the handle was
> + * registered, it will be invoked some time during, or after this
> + * function call, when it is safe to release the user data.
> + *
> * Returns 0 on success, -1 on failure
> */
> typedef int (*virEventRemoveTimeoutFunc)(int timer);
Okay, the API change looks fine, no problem for me.
and everything else seems to be a direct set of change related to the
extra callback function,
+1
Daniel
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel at veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
More information about the libvir-list
mailing list