[cairo] Cleaning up the PDF API

[Owen Taylor]

On Mon, 2005-05-16 at 16:15 -0700, Carl Worth wrote:
> On Mon, 16 May 2005 11:41:13 -0400, Kristian Høgsberg wrote:
> > No, this is different.  The cairo_destroy_func_t passed in here is
> > called when cairo_surface_finish() is called on the surface.  It's
> > responsible for e.g. flushing out any buffers and fclose()'ing FILE's at
> > the time we know that no more output will be going to the stream.
> 
> I was talking with Keith about this today. He had a good insight which
> I saw him type up, but I haven't seen it hit the list.
> 
> The point is that the final destruction of the surface is not under
> synchronous user control. Hence, the user_data callback is useful to
> inform the user about this asynchronously.
> 
> However, the active->finished transition only happens under explicitly
> user control, (a call to cairo_surface_finish). So if the user needs
> something to happen at that transition, the user can do so then.
> 
> In fact, this is the very purpose of cairo_surface_finish. It allows
> the user to force cairo to synchronize and finish its use of the
> surface so that the user knows that it is safe to flush buffers and
> close files etc.

The destroy function is there principally for language bindings. 
For, the language binding implementing:
 
 createFromPDF (InputStream stream)

suggested in the language binding appendix, say.

It's quite awkward if the language binding author has to insert code
into the binding for cairo_surface_finish() that checks to see if 
the surface is a PDF surface they created, and if so, frees the
InputStream.

Not only that, there is no conceptual reason that the language binding
couldn't hand off the object they created to some C code that
actually calls finish().

I'm fond of the idea that you should be able to bind each function
in an API basically one by one. That the language binding shouldn't
have to "understand" the relationship between different functions
to create a correct binding of the API.

Regards,
					Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050516/9e170d08/attachment.pgp