[cairo] Cleaning up the PDF API

[Kristian Høgsberg]

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.

He probably forgot to Cc the list.  I didn't notice that when I replied:

> Because this callback is strictly driven by this application-invoked
> function call,  there shouldn't be any need for an explicit callback.
> The application can manage to finish whatever output it wants to
> generate right after calling cairo_surface_finish.  That's why _finish
> exists, so the application can predict when the fflush/fclose can be
> called.

This is assuming that cairo_finish() is called by the same code that
creates the surface.  I don't know that that's a safe assumption to
make.

cheers,
Kristian

===

To elaborate, for cairo_surface_write_to_png_stream() we don't have a
destroy_callback function argument, since the code that creates the
closure and pass it to cairo_surface_write_to_png_stream() will also
destroy it - it will probably be within the same function.

Even though the cairo_surface_finish() operation is synchronous, and we
know that the closure data will no longer be needed after
cairo_surface_finish() completes, the code that calls
cairo_surface_finish() may not know how to destroy the closure data.
Maybe that part of the code doesn't even know what type of surface it's
dealing with.

Also, what are we trying to achieve here?  To reduce the number of
arguments or to make it easier to use?  Requiring the user to use user
data for the closure may reduce the number of arguments to the PDF
surface constructor and allow us to reuse the user data mechanism, but I
don't think it makes the API more transparent or easier to use.

cheers,
Kristian