Re: [pdf-devel] Object layer API

[jemarch]

Hi Gerel.

    > Please take a look and send your comments to discuss: it is capital to
    > come with a useful and complete API for the object layer.

   Of course, some comments follow.

Thanks :)

    > Note that:
    > 
    > [...]
    >
    > 3) It is not clear to me where to put the pdf creation functions
    >    (currently pdf_obj_new_array, etc). Since every object is
    >    associated with a document, it may be advisable to move the
    >    function names to pdf_obj_doc_new_array, etc...

   Well, we have two alternatives to model this relation in the API,

           1. Create a PDF object already associated to a document.
           2. Create a PDF object alone and then associate it to some document.

   Right now the API follows 1. I believe we should follow 2, and
   still have the current PDF object API procedures but as 'helpers',
   and with the prefix 'pdf_obj_doc_' in them instead.

   So, to add a new real we would do:
   ##
   pdf_obj_doc_new_real (doc, value);
   ###

   with the following definition:
   ##
   pdf_obj_doc_new_real (doc, value)
   {
     pdf_obj_doc_add (doc, pdf_obj_real_new (value));
   }
   ###

   This way we have modeled the relation and defined a clear scope for each 
module
   implementation (object and document), and yet have the helper
   pdf_obj_doc_new_real() that seems so obvious to be there.

Do you intend to publish the 'pdf_obj_real_new' function in the public
API?

    > 6) I am still working in the first draft of the internal architecture
    >    of the layer. Don't assume that the pdf_obj_doc_t type will be
    >    implemented in a different module than the pdf_obj_t type, for
    >    instance.

   Well, my previous comment is an argument in favour of splitting
   those types implementation, if that helps.



   BTW, by internal architecture draft do you mean this:
   http://www.gnupdf.org/manuals/gnupdf-arch.html/The-object-layer.html
   ?

No. It is just a quite brief introduction. I didn't commit the
architecture draft yet.

   I would rename procedures that end with 'put',
   i.e. 'pdf_xxx_xxx_put', to 'pdf_xxx_xxx_set'.

Agreed.

   Regarding objects collections, can some object collection be
   referenced with some ID within a PDF document ? (e.g. an indirect
   reference). I tried to find out with the PDF reference but nothing.

Each object collection is modeling one or more object streams. Objects
contained in objects streams are indirect.

   BTW, I read 'strong reference' in the object layer section but
   couldn't find any mention to them in the PDF reference. Any help ?

When we save an object document (using pdf_obj_doc_save) a garbage
collector is invoked on the objects of the saved document. The garbage
collector implements a sweep-mark process that, using the document
root dictionary as the root, marks any reachable object. Then, in the
sweep phase, every object not marked is collected.

The 'reference weakness' is a property of both dictionary and array
entries:

- If the entry is declared as a 'weak reference' then the object
  contained in that entry is not marked when the container object is
  marked.

- If the entry is declared as a 'strong reference' (= not weak) then
  the object contained in that entry is always marked, even if the
  container object is going to be collected and there are not more
  references to the object in the document.


-- 
Jose E. Marchesi  <address@hidden>
                  http://www.jemarch.net
GNU Project       http://www.gnu.org