Task7792
From GNUpdf
| Task #7792 | |
|---|---|
| Design of the Error Module | |
| State | STARTED |
| Priority | 5 |
| Estimated effort | 8ph |
| Scheduled | 01-01-2008 |
| Deadline | 02-02-2007 |
| Start | |
| End | |
| Assigned to | gerel |
| Savannah task | |
Contents |
Design of the Error Module
Overview
The Error module provides procedures for error reporting to the client as well as for error tracing (via debug messages) to developers. Here we also define status types returned by most procedures (there are exceptions though).
The idea of context-based errors is subject to each module implementation and I'm not sure how to deal with that right now. However I created the section for open discussion.
Description
This is the initial API for implementation.
Status Types
- pdf_status_t
- A status variable.
The following constants defines the valid values to be hold in a pdf_status_t variable:
- PDF_OK
- PDF_ERROR
- PDF_EBADDATA
- PDF_ENOMEM
- PDF_EEOF
- PDF_EDIVBYZERO
- PDF_ENONODE
- PDF_EINVRANGE
- PDF_ETEXTENC
- PDF_ENOMATCH
This list will grow as we get closer to a mature state of development.
I ask everyone working on some module to help me here. I just added the most general ones by reading the info document. Actually, some of them could be used on different modules, like PDF_EINVRANGE, when dealing with indexes.
Error reporting procedures
- Function: void pdf_perror (pdf_status_t status, const char *str)
- Prints the message corresponding to 'status' to stderr followed by 'str'
- Parameters
- status
- status code
- str
- a user-defined message
- status
- Returns
- nothing
- Function: void pdf_error (pdf_status_t status, FILE *fd, const char *format, ...)
- Prints a message with `fprintf (fd, format, ...)';
- if status is nonzero, also prints the corresponding message.
- Parameters
- status
- status/error code
- fd
- file descriptor open for writing
- format
- string format for the message
- ...
- format's arguments
- status
- Returns
- nothing
Debugging procedures
For each layer there is a macro procedure defined. The file name and the line number at which the error ocurred is printed to stderr followed by 'message'
- Macro: PDF_DEBUG_BASE (message, ...)
- Macro: PDF_DEBUG_OBJECT (message, ...)
- Macro: PDF_DEBUG_DOCUMENT (message, ...)
- Macro: PDF_DEBUG_PAGE (message, ...)
- Parameters
- message
- a 'const char*' string
- ...
- message's arguments
- message
- Returns
- nothing
An example call would be like:
PDF_DEBUG_BASE("Testing macro '%s' '%d' '%lf'", "string", 7, 10.1);
In case debugging is not enabled these macros should be defined to the null string.
Context-based Errors
Since the library will be thread-safe we can't share global variables. To deal with error tracing the idea of a 'context' will be introduced (like other libraries do [1] [2]).
As for the Error Module I think we should only provide a structure for error tracing that later would be part of each object's context, the latter being subject to the module's implementation.
References
Discussion thread for tracing/debugging/logging facility on mailing list
