[libvirt] [PATCH libvirt-glib] Add complete docs for the Libvirt GLib library
Daniel P. Berrange
berrange at redhat.com
Mon Apr 30 14:38:49 UTC 2012
From: "Daniel P. Berrange" <berrange at 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 @@
+ at 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
More information about the libvir-list
mailing list