From 6c5a22572518483cadaa2dea80e23fffa1578ca4 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Tue, 28 Feb 2006 13:58:30 +0000 Subject: [PATCH] * docs/errors.html docs/libvir.html docs/*: added a page about error handling and regenerated the docs Daniel --- ChangeLog | 5 ++ docs/FAQ.html | 2 +- docs/architecture.html | 2 +- docs/bugs.html | 2 +- docs/downloads.html | 2 +- docs/errors.html | 69 +++++++++++++++++++++++ docs/format.html | 2 +- docs/index.html | 7 ++- docs/intro.html | 2 +- docs/libvir.html | 121 ++++++++++++++++++++++++++++++++++++++++- docs/news.html | 2 +- docs/python.html | 2 +- docs/site.xsl | 3 + 13 files changed, 209 insertions(+), 12 deletions(-) create mode 100644 docs/errors.html diff --git a/ChangeLog b/ChangeLog index 00de3ae97f..c4901b2e9c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Feb 28 14:57:25 CET 2006 Daniel Veillard + + * docs/errors.html docs/libvir.html docs/*: added a page about + error handling and regenerated the docs + Tue Feb 28 13:12:50 CET 2006 Daniel Veillard * TODO: updated diff --git a/docs/FAQ.html b/docs/FAQ.html index f872108107..5680f92517 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -77,4 +77,4 @@ via the pkg-config command line tool, like:

pkg-config libvirt --libs

-

main menu

related links

Graphics and design by Diana Fong

+

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/architecture.html b/docs/architecture.html index f55e11d1e9..d8b6a626e6 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -24,4 +24,4 @@ connect to initialize the library. It will try to open the read-only socket /var/run/xenstored/socket_ro to connect to the Xen Store and also try to use the RPC to the Xen daemon. In this case use of hypervisor calls and write to the Xen Store will not be possible, restraining the amount -of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

+of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/bugs.html b/docs/bugs.html index fa84356bfb..f556a0b6a6 100644 --- a/docs/bugs.html +++ b/docs/bugs.html @@ -7,4 +7,4 @@ page and follow the instructions. Patches with explanations and provided as attachments are really appreciated and will be discussed on the mailing list. If possible generate the patches by using cvs diff -u in a CVS checkout.

We expect to use Red Hat Bugzilla to track bugs for libvirt, though there isn't a libvirt software -module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

+module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/downloads.html b/docs/downloads.html index 4b6298e40a..2c7ca142fb 100644 --- a/docs/downloads.html +++ b/docs/downloads.html @@ -7,4 +7,4 @@ available, first register onto the server:

cvs -d :pserver:anoncvs@l checkout the development tree with:

cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt

Use ./autogen.sh to configure the local checkout, then make and make install, as usual. All normal cvs commands are now -available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

+available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/errors.html b/docs/errors.html new file mode 100644 index 0000000000..00f7499475 --- /dev/null +++ b/docs/errors.html @@ -0,0 +1,69 @@ + + +Handling of errors

Handling of errors

The main goals of libvirt when it comes to error handling are:

  • provide as much detail as possible
    • +
  • provide the informations as soon as possible
    • +
  • dont force the library user into one style of error handling
    • +

As result the library provide both synchronous, callback based and +asynchronous error reporting. When an error happens in the library code the +error is logged, allowing to retrieve it later and if the user registered an +error callback it will be called synchronously. Once the call to libvirt ends +the error can be detected by the return value and the full information for +the last logged error can be retrieved.

To avoid as much as prossible troubles with a global variable in a +multithreaded environment, libvirt will associate when possible the errors to +the current connection they are related to, that way the error is stored in a +dynamic structure which can be made thread specific. Error callback can be +set specifically to a connection with

So error handling in the code is the following:

  1. if the error can be associated to a connection for example when failing + to look up a domain +
    1. if there is a callback associated to the connection set with virConnSetErrorFunc, + call it with the error informations
      2. +
    2. otherwise if there is a global callback set with virSetErrorFunc, + call it with the error information
      3. +
    3. otherwise call virDefaultErrorFunc + which is the default error function of the library issuing the error + on stderr
      4. +
    4. save the error in the connection for later retrieval with virConnGetLastError
      5. +
    2. +
  2. otherwise like when failing to create an hypervisor connection: +
    1. if there is a global callback set with virSetErrorFunc, + call it with the error information
      2. +
    2. otherwise call virDefaultErrorFunc + which is the default error function of the library issuing the error + on stderr
      3. +
    3. save the error in the connection for later retrieval with virGetLastError
      4. +
    3. +

In all cases the error informations are provided as a virErrorPtr pointer to +read-only structure virError containing the +following fields:

  • code: an error number from the virErrorNumber + enum
    • +
  • domain: an enum indicating which part of libvirt raised the error see + virErrorDomain
    • +
  • level: the error level, usually VIR_ERR_ERROR, though there is room for + warnings like VIR_ERR_WARNING
    • +
  • message: the full human-readable formatted string of the error
    • +
  • conn: if available a pointer to the virConnectPtr + connection to the hypervisor where this happened
    • +
  • dom: if available a pointer to the virDomainPtr domain + targetted in the operation
    • +

and then extra raw informations about the error which may be initialized +to 0 or NULL if unused

  • str1, str2, str3: string informations, usually str1 is the error + message format
    • +
  • int1, int2: integer informations
    • +

So usually, setting up specific error handling with libvirt consist of +registering an handler with with virSetErrorFunc or +with virConnSetErrorFunc, +chech the value of the code value, take appropriate action, if needed let +libvirt print the error on stderr by calling virDefaultErrorFunc. +For asynchronous error handing, set such a function doing nothing to avoid +the error being reported on stderr, and call virConnGetLastError or +virGetLastError when an API call returned an error value. It can be a good +idea to use virResetError or virConnResetLastError +once an error has been processed fully.

At the python level, there only a global reporting callback function at +this point, see the error.py example about it:

def handler(ctxt, err):
+    global errno
+
+    #print "handler(%s, %s)" % (ctxt, err)
+    errno = err
+
+libvirt.registerErrorHandler(handler, 'context')

the second argument to the registerErrorHandler function is passed as the +fist argument of the callback like in the C version. The error is a tuple +containing the same field as a virError in C, but cast to Python.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/format.html b/docs/format.html index a6d3d4ee52..b58a38e50a 100644 --- a/docs/format.html +++ b/docs/format.html @@ -65,4 +65,4 @@ children in no specific order:

  • source: indicating the bridge name
    • target: and optional target indicating the device name.

While the format may be extended in various ways as support for more hypervisor types and features are added, it is expected that this core subset -will remain functional in spite of the evolution of the library.

main menu

related links

Graphics and design by Diana Fong

+will remain functional in spite of the evolution of the library.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/index.html b/docs/index.html index 4e418720a5..a14827b2d4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -15,8 +15,8 @@

what is libvirt?

-

Libvirt is a C toolkit to interract with the virtualization capabilities of -recent versions of Linux (and other OSes). It is free software available +

Libvirt is a C toolkit to interract with the virtualization capabilities +of recent versions of Linux (and other OSes). It is free software available under the GNU Lesser General Public License. Virtualization of the Linux Operating System means the ability to run multiple instances of Operating Systems @@ -52,6 +52,9 @@ mechanisms if needed.

  • Binding for Python
    • +
  • + Handling of errors +
  • FAQ
    • diff --git a/docs/intro.html b/docs/intro.html index 6e28c9ccab..ed9334c486 100644 --- a/docs/intro.html +++ b/docs/intro.html @@ -27,4 +27,4 @@ and for applications focusing on virtualization of a single node (the only exception being domain migration between node capabilities which may need to be added at the libvirt level). Where possible libvirt should be extendable to be able to provide the same API for remote nodes, however this is not the -case at the moment, the code currently handle only local node accesses.

    main menu

    related links

    Graphics and design by Diana Fong

    +case at the moment, the code currently handle only local node accesses.

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/libvir.html b/docs/libvir.html index e60f273ec2..d54ea6be24 100644 --- a/docs/libvir.html +++ b/docs/libvir.html @@ -14,8 +14,8 @@ site

    what is libvirt?

    -

    Libvirt is a C toolkit to interract with the virtualization capabilities of -recent versions of Linux (and other OSes). It is free software available +

    Libvirt is a C toolkit to interract with the virtualization capabilities +of recent versions of Linux (and other OSes). It is free software available under the GNU Lesser General Public License. Virtualization of the Linux Operating System means the ability to run multiple instances of Operating Systems @@ -357,6 +357,123 @@ from the C API, the only points to notice are:

    associated to the virDomain class. +

    Handling of errors

    + +

    The main goals of libvirt when it comes to error handling are:

    +
      +
    • provide as much detail as possible
      • +
    • provide the informations as soon as possible
      • +
    • dont force the library user into one style of error handling
      • +
    + +

    As result the library provide both synchronous, callback based and +asynchronous error reporting. When an error happens in the library code the +error is logged, allowing to retrieve it later and if the user registered an +error callback it will be called synchronously. Once the call to libvirt ends +the error can be detected by the return value and the full information for +the last logged error can be retrieved.

    + +

    To avoid as much as prossible troubles with a global variable in a +multithreaded environment, libvirt will associate when possible the errors to +the current connection they are related to, that way the error is stored in a +dynamic structure which can be made thread specific. Error callback can be +set specifically to a connection with

    + +

    So error handling in the code is the following:

    +
      +
    1. if the error can be associated to a connection for example when failing + to look up a domain +
        +
      1. if there is a callback associated to the connection set with virConnSetErrorFunc, + call it with the error informations
        2. +
      2. otherwise if there is a global callback set with virSetErrorFunc, + call it with the error information
        3. +
      3. otherwise call virDefaultErrorFunc + which is the default error function of the library issuing the error + on stderr
        4. +
      4. save the error in the connection for later retrieval with virConnGetLastError
        5. +
      +
      2. +
    2. otherwise like when failing to create an hypervisor connection: +
        +
      1. if there is a global callback set with virSetErrorFunc, + call it with the error information
        2. +
      2. otherwise call virDefaultErrorFunc + which is the default error function of the library issuing the error + on stderr
        3. +
      3. save the error in the connection for later retrieval with virGetLastError
        4. +
      +
      3. +
    + +

    In all cases the error informations are provided as a virErrorPtr pointer to +read-only structure virError containing the +following fields:

    +
      +
    • code: an error number from the virErrorNumber + enum
      • +
    • domain: an enum indicating which part of libvirt raised the error see + virErrorDomain
      • +
    • level: the error level, usually VIR_ERR_ERROR, though there is room for + warnings like VIR_ERR_WARNING
      • +
    • message: the full human-readable formatted string of the error
      • +
    • conn: if available a pointer to the virConnectPtr + connection to the hypervisor where this happened
      • +
    • dom: if available a pointer to the virDomainPtr domain + targetted in the operation
      • +
    + +

    and then extra raw informations about the error which may be initialized +to 0 or NULL if unused

    +
      +
    • str1, str2, str3: string informations, usually str1 is the error + message format
      • +
    • int1, int2: integer informations
      • +
    + +

    So usually, setting up specific error handling with libvirt consist of +registering an handler with with virSetErrorFunc or +with virConnSetErrorFunc, +chech the value of the code value, take appropriate action, if needed let +libvirt print the error on stderr by calling virDefaultErrorFunc. +For asynchronous error handing, set such a function doing nothing to avoid +the error being reported on stderr, and call virConnGetLastError or +virGetLastError when an API call returned an error value. It can be a good +idea to use virResetError or virConnResetLastError +once an error has been processed fully.

    + +

    At the python level, there only a global reporting callback function at +this point, see the error.py example about it:

    +
    def handler(ctxt, err):
+    global errno
+
+    #print "handler(%s, %s)" % (ctxt, err)
+    errno = err
+
+libvirt.registerErrorHandler(handler, 'context')
    + +

    the second argument to the registerErrorHandler function is passed as the +fist argument of the callback like in the C version. The error is a tuple +containing the same field as a virError in C, but cast to Python.

    +

    FAQ

    Table of Contents:

    diff --git a/docs/news.html b/docs/news.html index 4013875fd1..a2f965fe8e 100644 --- a/docs/news.html +++ b/docs/news.html @@ -25,4 +25,4 @@ and check the ChangeLog to gauge progresses.

    0.0.1: Dec 19 2005

    • First release
    • Basic management of existing Xen domains
    • Minimal autogenerated Python bindings
      • -

    main menu

    related links

    Graphics and design by Diana Fong

    +

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/python.html b/docs/python.html index 17ac54e098..afe8bbe912 100644 --- a/docs/python.html +++ b/docs/python.html @@ -47,4 +47,4 @@ from the C API, the only points to notice are:

    • the import of the modu
    • extracting and printing some informations about the domain using various methods associated to the virDomain class.
      • -

    main menu

    related links

    Graphics and design by Diana Fong

    +

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/site.xsl b/docs/site.xsl index 7ea1b0a542..7fb496398e 100644 --- a/docs/site.xsl +++ b/docs/site.xsl @@ -27,6 +27,9 @@ help.html + + errors.html + downloads.html -- GitLab