Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/errors.html.in | 84 ---------------------------------- docs/errors.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 110 insertions(+), 85 deletions(-) delete mode 100644 docs/errors.html.in create mode 100644 docs/errors.rst diff --git a/docs/errors.html.in b/docs/errors.html.in deleted file mode 100644 index ea4272822f..0000000000 --- a/docs/errors.html.in +++ /dev/null @@ -1,84 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1 >Handling of errors</h1> - <p>The main goals of libvirt when it comes to error handling are:</p> - <ul> - <li>provide as much detail as possible</li> - <li>provide the information as soon as possible</li> - <li>dont force the library user into one style of error handling</li> - </ul> - <p>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.</p> - <p>To avoid as much as possible 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</p> - <p>So error handling in the code is the following:</p> - <ol> - <li>if the error can be associated to a connection for example when failing - to look up a domain - <ol><li>if there is a callback associated to the connection set with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>, - call it with the error information</li><li>otherwise if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>, - call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a> - which is the default error function of the library issuing the error - on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li></ol></li> - <li>otherwise like when failing to create a hypervisor connection: - <ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>, - call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a> - which is the default error function of the library issuing the error - on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li></ol></li> - </ol> - <p>In all cases the error information is provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to -read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the -following fields:</p> - <ul> - <li>code: an error number from the <a href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a> - enum</li> - <li>domain: an enum indicating which part of libvirt raised the error see - <a href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li> - <li>level: the error level, usually VIR_ERR_ERROR, though there is room for - warnings like VIR_ERR_WARNING</li> - <li>message: the full human-readable formatted string of the error</li> - <li>conn: if available a pointer to the <a href="html/libvirt-libvirt-host.html#virConnectPtr">virConnectPtr</a> - connection to the hypervisor where this happened</li> - <li>dom: if available a pointer to the <a href="html/libvirt-libvirt-domain.html#virDomainPtr">virDomainPtr</a> domain - targeted in the operation</li> - </ul> - <p>and then extra raw information about the error which may be initialized -to 0 or NULL if unused</p> - <ul> - <li>str1, str2, str3: string information, usually str1 is the error - message format</li> - <li>int1, int2: integer information</li> - </ul> - <p>So usually, setting up specific error handling with libvirt consist of -registering a handler with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or -with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>, -check the value of the code value, take appropriate action, if needed let -libvirt print the error on stderr by calling <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>. -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 <a href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a> -once an error has been processed fully.</p> - <p>At the python level, there only a global reporting callback function at -this point, see the error.py example about it:</p> - <pre>def handler(ctxt, err): - global errno - - #print "handler(%s, %s)" % (ctxt, err) - errno = err - -libvirt.registerErrorHandler(handler, 'context') </pre> - <p>the second argument to the registerErrorHandler function is passed as the -first 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.</p> - </body> -</html> diff --git a/docs/errors.rst b/docs/errors.rst new file mode 100644 index 0000000000..07c0fb1fc0 --- /dev/null +++ b/docs/errors.rst @@ -0,0 +1,109 @@ +================== +Handling of errors +================== + +The main goals of libvirt when it comes to error handling are: + +- provide as much detail as possible +- provide the information 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 possible 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: + +#. if the error can be associated to a connection for example when failing to + look up a domain + + #. if there is a callback associated to the connection set with + `virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, + call it with the error information + #. otherwise if there is a global callback set with + `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it + with the error information + #. otherwise call + `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__ + which is the default error function of the library issuing the error on + stderr + #. save the error in the connection for later retrieval with + `virConnGetLastError <html/libvirt-virterror.html#virConnGetLastError>`__ + +#. otherwise like when failing to create a hypervisor connection: + + #. if there is a global callback set with + `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it + with the error information + #. otherwise call + `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__ + which is the default error function of the library issuing the error on + stderr + #. save the error in the connection for later retrieval with + `virGetLastError <html/libvirt-virterror.html#virGetLastError>`__ + +In all cases the error information is provided as a +`virErrorPtr <html/libvirt-virterror.html#virErrorPtr>`__ pointer to read-only +structure `virError <html/libvirt-virterror.html#virError>`__ containing the +following fields: + +- code: an error number from the + `virErrorNumber <html/libvirt-virterror.html#virErrorNumber>`__ enum +- domain: an enum indicating which part of libvirt raised the error see + `virErrorDomain <html/libvirt-virterror.html#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 <html/libvirt-libvirt-host.html#virConnectPtr>`__ connection + to the hypervisor where this happened +- dom: if available a pointer to the + `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__ domain + targeted in the operation + +and then extra raw information about the error which may be initialized to 0 or +NULL if unused + +- str1, str2, str3: string information, usually str1 is the error message + format +- int1, int2: integer information + +So usually, setting up specific error handling with libvirt consist of +registering a handler with +`virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__ or with +`virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, check +the value of the code value, take appropriate action, if needed let libvirt +print the error on stderr by calling +`virDefaultErrorFunc <html/libvirt-virterror.html#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 <html/libvirt-virterror.html#virResetLastError>`__ or +`virConnResetLastError <html/libvirt-virterror.html#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 first +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. diff --git a/docs/meson.build b/docs/meson.build index e92ce6bd9e..d0c1217351 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -39,7 +39,6 @@ docs_html_in_files = [ 'drvvirtuozzo', 'drvvmware', 'drvxen', - 'errors', 'firewall', 'formatcaps', 'formatdomaincaps', @@ -93,6 +92,7 @@ docs_rst_files = [ 'developer-tooling', 'drvqemu', 'drvch', + 'errors', 'formatbackup', 'formatcheckpoint', 'formatdomain', -- 2.35.1
