Re: [pdf-devel] Error management

[gerel]

 > From: address@hidden
 > 
 > Since the base layer of the library does not provide a common context and
 > since the functionality implemented by the several base modules are
 > relatively independent, we could use a simple error management schema for the
 > base layer:
 > 
 > - Procedures (functions not returning a single value) should return a
 > `pdf_status_t' value (enum defined in `pdf_error.h') that indicates success
 > (PDF_NOERROR == 0) or a specific error code (negative value,
 > i.e. PDF_E_NOMEM).
 >   
 >   Example:
 > 
 >     if (!pdf_stm_close (stm)) { /* Manage error */ }
 > 
 > - Functions (functions returning a single value) may define an "error value"
 > to return if an error has happened. The election of the error value depends
 > on the physical and logical range of the function:
 > 
 >   - Functions returning pointers: NULL Functions returning non-zero values: 0
 >   - ...
 > 
 >   There may be cases where it is not possible (or desirable) to provide an
 >   error value in the physical range of the function:
 > 
 >      pdf_real_t pdf_real_pow (pdf_real_t base, pdf_real_t exp);
 > 
 >   There may be also cases where a trick is done in order to provide a bigger
 >   physical range in order to hold error values:
 > 
 >      int pdf_stm_read_char (pdf_stm_t stm);
 > 
 >   The availability of an "error value" (or values) for a specific function
 >   should be documented in the library reference manual.
 > 
 > The client of the base layer is then expected to manage any error status
 > returned by a function.

On this layer the lib/error.h API would be suitable ?  (actually with some
changes like giving the caller the choice to write to 'stderr' or any other
output buffer, as behdad suggested)

 > The Object Layer of the library provides a context in which all operations
 > are made: the object-level document. In that case we could embed the logic of
 > error contexts inside the object-level documents and the library would still
 > be reentrant:
 > 
 >      pdf_o_some_operation (pdf_o_doc_t doc, arguments...)  /* Check for
 >      errors in `doc' */
 > 
 > The pdf_error module could then implement the abstractions used inside
 > pdf_o_docs: a stack of pdf_status_t, etc.
 > 
 > A similar solution could be used for the Document Layer and the Page Layer
 > using `pdf_d_doc_t' as the context.
 > 
 > Anyway the important issue now is to agree in a suitable schema to be used in
 > the base layer. We will be able to extend the pdf_error module in the future
 > if needed.
 > 
 > Any feedback about this?

It looks like a good idea :-)

As a final question, does this mean we will need both APIs (i.e. lib/error.h and
a context-based new one) ?

OTOH, I have a few personal questions:

1. Under this schema can we say that errors at the base layer represent "serious
   problems" / "incorrigible errors" ?

2. For what I see the Document *Module* implements the Document Structure
   abstraction (section 3.6 in PDF 1.7 ref). Now I guess the Document *Layer* is
   another abstraction we need but is not explicitly defined on PDF 1.7 ref,
   am I right ?


cheers

-gerel