May 2012 - Devel - libvirt List Archives

[libvirt] [PATCH 0/3] usb devices with same vendor, productID hotplug support
by Guannan Ren 01 May '12

01 May '12

https://bugzilla.redhat.com/show_bug.cgi?id=815755 The set of patch tries to fix the issue when multiple usb devices with same idVendor, idProduct are availible on host, the usb device with lowest bus:device will be attached to guest if usb xml file is given like this: <hostdev mode='subsystem' type='usb' managed='yes'> <source> <vendor id='0x15e1'/> <product id='0x2007'/> </source> </hostdev> The reason is that the usb hotplug function searchs usb device in system files to match vendor and product id, the file with lowest number is always found first. After fix, in this case, libvirt will report an error like: At the same time, the usb part of domain initilization is also update in patch 2/3 # virsh attach-device rhel6u1 /tmp/usb.xml error: Failed to attach device from /tmp/usb.xml error: XML error: multiple USB deivces 15e1:2007, use <address> to specify one.

3 7

[libvirt] ANNOUNCE: Stable release libvirt-0.9.11.1
by Cole Robinson 01 May '12

01 May '12

I'm pleased to announce the release of libvirt-0.9.11.1. This is libvirt-0.9.11 with additional bugfixes that have accumulated upstream since the initial release. This release can be downloaded at: http://libvirt.org/sources/libvirt-0.9.11.1.tar.gz For a complete list of changes since libvirt-0.9.11 GA, please see: http://wiki.libvirt.org/page/Stable_Releases Thanks, Cole

3 2

[libvirt] [PATCH libvirt-glib] Add complete docs for the Libvirt GLib library
by Daniel P. Berrange 01 May '12

01 May '12

From: "Daniel P. Berrange" <berrange(a)redhat.com> Flesh out the section intros for each of the Libvirt GLib library modules, providing using examples where needed, and adding any missing function docs. --- cfg.mk | 2 +- configure.ac | 1 + docs/libvirt-glib/Libvirt-glib-docs.xml | 7 +-- docs/libvirt-glib/Makefile.am | 2 + docs/libvirt-glib/version.xml.in | 1 + libvirt-glib/libvirt-glib-error.c | 56 +++++++++++++++++++---- libvirt-glib/libvirt-glib-event.c | 65 ++++++++++++++++++++++++++ libvirt-glib/libvirt-glib-main.c | 76 +++++++++++++++++++++++++++++++ 8 files changed, 198 insertions(+), 12 deletions(-) create mode 100644 docs/libvirt-glib/version.xml.in diff --git a/cfg.mk b/cfg.mk index ed46aee..099ffa3 100644 --- a/cfg.mk +++ b/cfg.mk @@ -124,7 +124,7 @@ sc_check_author_list: test $$fail = 0 -exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/ +exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/|libvirt-glib/libvirt-glib-event.c|libvirt-glib/libvirt-glib-main.c exclude_file_name_regexp--sc_preprocessor_indentation = ^*/*.[ch] diff --git a/configure.ac b/configure.ac index 31f82c9..4b974d4 100644 --- a/configure.ac +++ b/configure.ac @@ -259,6 +259,7 @@ AC_OUTPUT(Makefile vapi/Makefile docs/Makefile docs/libvirt-glib/Makefile + docs/libvirt-glib/version.xml docs/libvirt-gobject/Makefile docs/libvirt-gconfig/Makefile libvirt-glib-1.0.pc diff --git a/docs/libvirt-glib/Libvirt-glib-docs.xml b/docs/libvirt-glib/Libvirt-glib-docs.xml index 5b6a873..f2f3572 100644 --- a/docs/libvirt-glib/Libvirt-glib-docs.xml +++ b/docs/libvirt-glib/Libvirt-glib-docs.xml @@ -3,21 +3,22 @@ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> + <!ENTITY version SYSTEM "version.xml"> ]> <book id="index"> <bookinfo> - <title>Libvirt-glib Reference Manual</title> + <title>Libvirt GLib Reference Manual</title> </bookinfo> <chapter> - <title>Libvirt-glib</title> + <title>API Reference</title> <xi:include href="xml/libvirt-glib-main.xml"/> <xi:include href="xml/libvirt-glib-error.xml"/> <xi:include href="xml/libvirt-glib-event.xml"/> </chapter> <chapter id="object-tree"> <title>Object Hierarchy</title> - <xi:include href="xml/tree_index.sgml"/> + <xi:include href="xml/tree_index.sgml"/> </chapter> <index id="api-index-full"> <title>API Index</title> diff --git a/docs/libvirt-glib/Makefile.am b/docs/libvirt-glib/Makefile.am index e45f4e2..186f8ff 100644 --- a/docs/libvirt-glib/Makefile.am +++ b/docs/libvirt-glib/Makefile.am @@ -39,3 +39,5 @@ GTKDOC_LIBS = \ $(top_builddir)/libvirt-glib/libvirt-glib-1.0.la include $(top_srcdir)/gtk-doc.make + +EXTRA_DIST += version.xml.in diff --git a/docs/libvirt-glib/version.xml.in b/docs/libvirt-glib/version.xml.in new file mode 100644 index 0000000..d78bda9 --- /dev/null +++ b/docs/libvirt-glib/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/libvirt-glib/libvirt-glib-error.c b/libvirt-glib/libvirt-glib-error.c index 4a44216..7356aed 100644 --- a/libvirt-glib/libvirt-glib-error.c +++ b/libvirt-glib/libvirt-glib-error.c @@ -29,11 +29,51 @@ #include "libvirt-glib/libvirt-glib.h" /** - * gvir_error_new: (skip) + * SECTION:libvirt-glib-error + * @short_description: Convert libvirt error reports to GLib error reports + * @title: Error reporting + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The libvirt API uses the <code>virError</code> structure for reporting + * errors back to the application programmer. The libvirt API errors are + * provided in thread-local variables, while the GLib standard practice is + * to return errors via out parameters. This library provides a simple way + * to fill in <code>GError **</code> output parameters with the contents + * of the most recent libvirt error object in the current thread. + * + * The <code>gvir_error_new</code>, <code>gvir_error_new_literal</code> and + * <code>gvir_error_new_valist</code> methods all return a newly created + * <code>GError *</code> object instance, differing only in the way the + * message needs to be provided. For most usage though, it is preferrable + * to use the <code>gvir_set_error</code>, <code>gvir_set_error_literal</code> + * and <code>gvir_set_error_valist</code> methods. These all accept a + * <code>GError **</code> argument and take care to only fill it if it + * points to a non-NULL location. + * + * <example> + * <title>Reporting GLib errors with libvirt APIs</title> + * <programlisting><![CDATA[ + * gboolean myapp_start_guest(const gchar *xml, GError **error) + * { + * if (virDomainCreate(conn, xml, 0) < 0) { + * gvir_set_error_literal(error, "Unable to start virtual machine"); + * return FALSE; + * } + * + * return TRUE; + * } + * ]]></programlisting> + * </example> + * + */ + +/** + * gvir_error_new: * @domain: error domain * @code: error code * @format: printf()-style format for error message - * @Varargs: parameters for message format + * @...: parameters for message format * * Creates a new #GError with the given @domain and @code, * and a message formatted with @format. @@ -61,7 +101,7 @@ GError *gvir_error_new(GQuark domain, } /** - * gvir_error_new_literal: (skip) + * gvir_error_new_literal: * @domain: error domain * @code: error code * @message: error message @@ -99,7 +139,7 @@ GError *gvir_error_new_literal(GQuark domain, } /** - * gvir_error_new_valist: (skip) + * gvir_error_new_valist: * @domain: error domain * @code: error code * @format: printf()-style format for error message @@ -129,12 +169,12 @@ GError *gvir_error_new_valist(GQuark domain, /** - * gvir_set_error: (skip) + * gvir_set_error: * @error: pointer to error location * @domain: error domain * @code: error code * @format: printf()-style format for error message - * @Varargs: parameters for message format + * @...: parameters for message format * * If @error is NULL this does nothing. Otherwise it * creates a new #GError with the given @domain and @code, @@ -164,7 +204,7 @@ void gvir_set_error(GError **error, /** - * gvir_set_error_literal: (skip) + * gvir_set_error_literal: * @error: pointer to error location * @domain: error domain * @code: error code @@ -190,7 +230,7 @@ void gvir_set_error_literal(GError **error, /** - * gvir_set_error_valist: (skip) + * gvir_set_error_valist: * @error: pointer to error location * @domain: error domain * @code: error code diff --git a/libvirt-glib/libvirt-glib-event.c b/libvirt-glib/libvirt-glib-event.c index 6d54b10..94f4de8 100644 --- a/libvirt-glib/libvirt-glib-event.c +++ b/libvirt-glib/libvirt-glib-event.c @@ -31,6 +31,53 @@ #include "libvirt-glib/libvirt-glib.h" +/** + * SECTION:libvirt-glib-event + * @short_description: Integrate libvirt with the GMain event framework + * @title: Event loop + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The libvirt API has the ability to provide applications with asynchronous + * notifications of interesting events. To enable this functionality though, + * applications must provide libvirt with an event loop implementation. The + * libvirt-glib API provides such an implementation, which naturally integrates + * with the GMain event loop framework. + * + * To enable use of the GMain event loop glue, the <code>gvir_event_register()</code> + * should be invoked. Once this is done, it is mandatory to have the default + * GMain event loop run by a thread in the application, usually the primary + * thread, eg by using <code>gtk_main()</code> or <code>g_application_run()</code> + * + * <example> + * <title>Registering for events with a GTK application</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * gvir_event_register(); + * ...more setup... + * gtk_main(); + * return 0; + * } + * ]]></programlisting> + * </example> + * + * <example> + * <title>Registering for events using Appplication</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * GApplication *app = ...create some impl of GApplication... + * gvir_event_register(); + * ...more setup... + * g_application_run(app); + * return 0; + * } + * ]]></programlisting> + * </example> + */ + + #if GLIB_CHECK_VERSION(2, 31, 0) #define g_mutex_new() g_new0(GMutex, 1) #endif @@ -414,6 +461,24 @@ static gpointer event_register_once(gpointer data G_GNUC_UNUSED) return NULL; } + +/** + * gvir_event_register: + * + * Registers a libvirt event loop implementation that is backed + * by the default <code>GMain</code> context. If invoked more + * than once this method will be a no-op. Applications should, + * however, take care not to register any another non-GLib + * event loop with libvirt. + * + * After invoking this method, it is mandatory to run the + * default GMain event loop. Typically this can be satisfied + * by invoking <code>gtk_main</code> or <code>g_application_run</code> + * in the application's main thread. Failure to run the event + * loop will mean no libvirt events get dispatched, and the + * libvirt keepalive timer will kill off libvirt connections + * frequently. + */ void gvir_event_register(void) { static GOnce once = G_ONCE_INIT; diff --git a/libvirt-glib/libvirt-glib-main.c b/libvirt-glib/libvirt-glib-main.c index 0cb2dd5..3389de9 100644 --- a/libvirt-glib/libvirt-glib-main.c +++ b/libvirt-glib/libvirt-glib-main.c @@ -29,6 +29,36 @@ #include "libvirt-glib-main.h" +/** + * SECTION:libvirt-glib-main + * @short_description: Initialize the library + * @title: Library initialization + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The Libvirt GLib library provides glue to integrate core libvirt + * infrastructure with the GLib library. This enables consistent + * error reporting procedures and a common event loop implementation + * for applications. + * + * Before using any functions in the Libvirt GLib library, it must be initialized + * by calling <code>gvir_init</code> or <code>gvir_init_check</code>. + * + * <example> + * <title>Initializing the Libvirt GLib library</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * gvir_init(&argc, &argv); + * ...more setup... + * gtk_main(); + * return 0; + * } + * ]]></programlisting> + * </example> + * + */ + static void gvir_error_func(gpointer opaque G_GNUC_UNUSED, virErrorPtr err) @@ -37,6 +67,33 @@ gvir_error_func(gpointer opaque G_GNUC_UNUSED, } + +/** + * gvir_init: + * @argc: (inout): Address of the argc parameter of your main() function (or 0 + * if argv is NULL). This will be changed if any arguments were handled. + * @argv: (array length=argc) (inout) (allow-none): Address of the + * <parameter>argv</parameter> parameter of main(), or %NULL. Any options + * understood by GTK+ are stripped before return. + * + * Call this function before using any other Libvirt GLib functions in your applications. + * It will initialize everything needed to operate the toolkit and parses some standard + * command line options. + * + * Although you are expected to pass the @argc, @argv parameters from main() to this + * function, it is possible to pass NULL if @argv is not available or commandline + * handling is not required. + * + * @argc and @argv are adjusted accordingly so your own code will never see those + * standard arguments. + * + * This method will also turn on debug logging of the library if the + * <literal>LIBVIRT_GLIB_DEBUG</literal> environment variable is set. + * + * This function will terminate your program if it was unable to initialize + * for some reason. If you want the program to fall back to an alternate + * mode of operation call <code>gvir_init_check</code> instead. + */ void gvir_init(int *argc, char ***argv) { @@ -58,6 +115,25 @@ static void gvir_log_handler(const gchar *log_domain G_GNUC_UNUSED, } +/** + * gvir_init_check: + * @argc: (inout): Address of the argc parameter of your main() function (or 0 + * if argv is NULL). This will be changed if any arguments were handled. + * @argv: (array length=argc) (inout) (allow-none): Address of the + * <parameter>argv</parameter> parameter of main(), or %NULL. Any options + * understood by GTK+ are stripped before return. + * @err: filled with the error information if initialized failed. + * + * This function does the same work as gvir_init() with only a single + * change: It does not terminate the program if the Libvirt GLib library + * can't be initialized. Instead it returns %FALSE on failure. + * + * This way the application can fall back to some other mode of + * operation. + * + * Return value: %TRUE if the library was successfully initialized, + * %FALSE otherwise + */ gboolean gvir_init_check(int *argc G_GNUC_UNUSED, char ***argv G_GNUC_UNUSED, GError **err G_GNUC_UNUSED) -- 1.7.10

2 1