[cairo] Cleaning up the PDF API

[Kristian Høgsberg]

On Mon, 2005-05-16 at 16:54 -0700, Carl Worth wrote:
...
> > 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.
> 
> I agree. And I think that usage of cairo in some language other than C
> should not have a model drastically different than usage of cairo in
> C. But I don't see why cairo_pdf_surface_create_for_stream must accept
> a finish-time callback in order to allow this.

OK, I think some of the confusion that has kept this thread alive is
that finishing the surface is different from destroying the stream
closure.  We shouldn't destroy the stream closure at finish time, just
as we don't destroy user supplied drawables in the xlib surface finish
call or user supplied pixel data in the image surface finish call.  If
we want the surface to "assume ownership" of the stream closure, we can
attach it as user data with a suitable destroy callback as Carl
suggested earlier.  The stream closure won't be destroyed until the
surface is destroyed, but that shouldn't matter we've written out the
entire pdf at this point.

Or, well, that depends on the buffering sematics of the stream api.
I've assumed buffered I/O for now, so to make finish() work as
documented we need to either:

1. Trade the destroy callback for a flush callback.
2. Assume non-buffered I/O and add buffering to cairo_output_stream_t
3. Decide that a write of 0 bytes means "flush" (just a variant of 1)

cheers,
Kristian