jimb@tigris.org writes:
> * include/svn_fs.h (svn_fs_free_file_contents): Function deleted.
> svn_fs_file_contents no longer returns a baton; instead, it returns an
> svn_stream_t, which should be freed using svn_stream_close.
Let's talk about that last sentence.
Here's a quote from svn_io.h, where GregH is decribing our generic
stream interface:
The creator of a stream sets functions to handle read and write.
Both of these handlers accept a baton whose value is determined at
stream creation time; this baton can point to a structure
containing data associated with the stream. If a caller attempts
to invoke a handler which has not been set, it will generate a
runtime assertion failure. The creator can also set a handler for
close requests so it can clean up data associated with the baton;
if a close handler is not specified, a close request on the stream
will simply be ignored. Note that svn_stream_close() does not
deallocate the memory associated with the stream; destroy the pool
you created the stream in to do that.
So in GregH's last sentence, what does "memory associated with the
stream" mean? Does it mean "the memory in which the stream structure
is allocated"? Or does it also mean "any memory used in the process
of accessing the stream"?
And what does his phrase "data associated with the baton" mean?
Remember that users calling svn_stream_close() have no idea that any
kind of stream-baton was created under the hood. Most of them will
think what Jim assumed in his commit message: that svn_stream_close
will somehow free the stream object itself.
In any case, I'm wondering how these promises relate to the actual
current implementation of svn_fs_file_contents() and the read-stream
it returns. Right now, the stream object is being allocated in the
provided pool, *and* the secret "baton" (which contains a copy of the
entire contents of the file) is also being allocated there.
So -- my interpretation of this interface is that svn_stream_close()
should destroy only the invisible baton containing file contents.
To deallocate the stream object, just free the original pool.
(Of course, why would anyone *want* that kind of control? What use
would the stream object be if its hidden baton were destroyed? Why
would you even want the stream object around anymore?)
Thoughts? Is this interpretation correct?
Received on Sat Oct 21 14:36:25 2006