Design Goals

Error processing in XGL was designed to do the following:

• Allow an application to provide its own error reporting function(s)
• Allow a device pipeline to provide its own error file containing error messages specific to the pipeline
• Provide for internationalization of error message strings
• Maintain state information when an error is detected that defines the error, its cause, and where it occurred

Overview of Error Handling

Error handling in XGL can be viewed in two ways: externally and internally. The external view describes what the user sees at the API level when an error occurs. The internal view describes how the error is handled by functions that are not visible at the API level.

External Error Handling Mechanism

Externally, from the API point of view, when an XGL application causes an error, the error notification function determines the application-visible response. Because this function is settable by the application, its response can vary depending on its current definition. The default error notification function sends an error message to stderr. For example, the following message is produced by the default function for a malloc error that occurs within an xgl_polygon() call from a 3D Context:

Error number di-1: malloc or new failed: out of memory Operator: xgl_polygon Object: XGL_3D_CTX

Error Notification Function

The XGL-provided default error notification function is defined in Error.h. When an error occurs, this function sends an ASCII string to the standard error output. The string consists of the XGL error code associated with the error, a message describing the error, the XGL operator being executed when the error was detected, the XGL object being used when the error was detected, and other optional information.

XGL enables an application to supply its own error notification function for filtering errors and reporting them to the application program. The following code fragment shows an example of an application error notification function.

#include <xgl/xgl.h> static Xgl_sgn32 newNotify(system_state) Xgl_sys_state system_state; { Xgl_error_info info; int n; xgl_object_get (system_state, XGL_SYS_ST_ERROR_INFO, &info); printf ("id = %s\n", info.id); printf ("msg = %s\n", info.msg); printf ("cur_op = %s\n", info.cur_op); printf ("cur_obj = %s\n", info.cur_obj); n = atoi (info.id); if (n < 100) { printf ("Non-Recoverable Error!\n"); } else { printf ("Recoverable Error!\n"); } return(1); }

This function uses the information in the Xgl_error_info structure returned by XGL_SYS_ST_ERROR_INFO to handle errors. Any of the eight fields in the structure can be used to filter errors. The System State attribute XGL_SYS_ST_ERROR_NOTIFICATION_FUNCTION sets the application-specific error function. The interface for the error notification function is as follows:

my_error_notify_func(Xgl_sys_state   sys_state);

Error Types and Categories

XGL errors are grouped into the five categories listed in Table 6-1 on page 108. These error categories enable an application programmer creating a new error notification function to detect a particular error group and respond accordingly. Errors in these categories can be further classified into

RECOVERABLE or NON-RECOVERABLE error types, as described in Table 6-2. This table also describes the relationship between error types and categories.

Note that the XGL default error notification function does not use the error types and categories. These are provided for developers who want to trap specific error types or categories in their own error notification function.

Table 6-1

Category	Description
SYSTEM	Internal errors, unsupported features, and errors that generally cannot be fixed by changing the application.
CONFIGURATION	Errors caused by improper installation or configuration of XGL (such as a .so file not found).
RESOURCE	Unavailable resource errors including both hardware and software resources (such as memory, shared memory, window ID, frame buffer).
ARITHMETIC	Arithmetic exceptions (such as an error resulting from dividing by 0 or taking the square root of -1).
USER	Errors caused by invalid function parameters, non-existent user files, or situations that may be caused by application program logic errors.

Table 6-2

Type	Description
NON-RECOVERABLE	XGL immediately aborts processing and returns control to the caller. Includes SYSTEM and CONFIGURATION errors, most RESOURCE errors, and some ARITHMETIC errors.
RECOVERABLE	XGL makes assumptions about what the application intended to do. Includes some RESOURCE errors, most ARITHMETIC errors, all USER errors.

Error Message Files

Binary-encoded files containing the English versions of error message strings are located in:

{path}/{LANG}/LC_MESSAGES/file.mo

where {path} is $XGLHOME/lib/locale if $XGLHOME is set, or /opt/SUNWits/Graphics-sw/xgl-3.0/lib/locale if $XGLHOME is not set. {LANG} is en for English language messages. Error message files that have been localized to the native language of the user will be found in other {LANG} directories.

More than one error message file may exist in this directory. At the very least, there is a file called xgl.mo, containing device-independent error messages. There may also be a file named xgl<company abbrev><pipeline abbrev>.mo, which contains error messages specific to the device pipeline. The directory path of the error message file is specified internally and cannot be set or retrieved via the XGL API.

Internal Error Handling Mechanism

Internally, when XGL detects an error, it calls an internal error handling function. This function assigns values to error attributes, searches for the error file that contains localized error messages, and retrieves the appropriate error message string. When the error message string is retrieved, the error handling function calls the application-settable error notification function for further processing of the error.

Error processing is handled centrally in a device-independent manner by the System State object. For maintainability, however, most error-specific attributes and methods are defined in a separate Error class.

The System State class defines the API interface functions used for error processing and contains error attributes exposed at the API. The Error class contains the default error notification function, functions that initialize the path to the error file, and a function used for error notification when System State

creation fails. The Error class also defines the error attributes for the System State object. Other attributes in the Error class define state information that is saved when an error occurs. These are shown in Table 6-3.

Table 6-3

Information	Description
Type	RECOVERABLE or NON-RECOVERABLE
Category	SYSTEM, CONFIGURATION, RESOURCE, ARITHMETIC, USER
ID	An error number in the form: <pipeline abbrev.>-##
Message	An error message string
Operator	XGL API operator in use when the error occurred
Object	XGL object in use when the error occurred
Operands	Two operands of error notification

When the System State object is initialized at xgl_open(), it instantiates an Error object and saves a pointer to the object. The Error object instantiation also defines the default error notification function.

When an error is detected, one of two internal error handling functions, reportError() or reportDiError() in the System State object, is called. These functions store current state information into the Error object. The error handling function invokes another internal routine, errorHandler() in the Error object, which gets the state information from the Error object and passes it to the current error notification function. It then invokes the error notification function to complete the error processing.

The state information in the Error object is overwritten when the next error occurs. Thus, the information stored in the Error object and referenced by the System State object is valid only during the invocation and execution of the error notification function.

---

Note - The Error object must be accessed immediately after the occurrence of an error, or the state information used by the error notification function may not be accurate.

---