Beautiful Code [90]
To understand the interface, even in its abridged form, you'll need to know some Subversion jargon:
pools
The pool arguments are memory pools—allocation buffers that allow a large number of objects to be freed simultaneously.
svn_error_t
The return type svn_error_t simply means that the function returns a pointer to a Subversion error object; a successful call returns a null pointer.
text delta
A text delta is the difference between two different versions of a file; you can apply a text delta as a patch to one version of the file to produce the other version. In Subversion, the "text" of a file is considered binary data—it doesn't matter whether the file is plain text, audio data, an image, or something else. Text deltas are expressed as streams of fixed-sized windows, each window containing a chunk of binary diff data. This way, peak memory usage is proportional to the size of a single window, rather than to the total size of the patch (which might be quite large in the case of, say, an image file).
window handler
This is the function prototype for applying one window of text-delta data to a target file.
baton
This is a void * data structure that provides context to a callback function. In other APIs, these are sometimes called void *ctx, void *userdata, or void *closure. Subversion calls them "batons" because they're passed around a lot, like batons in a relay race.
The interface starts with an introduction, to put a reader of the code in the right frame of mind. This text is almost unchanged since Jim Blandy wrote it in August of 2000, so the general concept has clearly weathered well:
Code View: Scroll / Show All
/** Traversing tree deltas.
*
* In Subversion, we've got various producers and consumers of tree
* deltas.
*
* In processing a `commit' command:
* - The client examines its working copy data, and produces a tree
* delta describing the changes to be committed.
* - The client networking library consumes that delta, and sends them
* across the wire as an equivalent series of network requests.
* - The server receives those requests and produces a tree delta --
* hopefully equivalent to the one the client produced above.
* - The Subversion server module consumes that delta and commits an
* appropriate transaction to the filesystem.
*
* In processing an `update' command, the process is reversed:
* - The Subversion server module talks to the filesystem and produces
* a tree delta describing the changes necessary to bring the
* client's working copy up to date.
* - The server consumes this delta, and assembles a reply
* representing the appropriate changes.
* - The client networking library receives that reply, and produces a
* tree delta --- hopefully equivalent to the one the Subversion
* server produced above.
* - The working copy library consumes that delta, and makes the
* appropriate changes to the working copy.
*
* The simplest approach would be to represent tree deltas using the
* obvious data structure. To do an update, the server would
* construct a delta structure, and the working copy library would
* apply that structure to the working copy; the network layer's job
* would simply be to get the structure across the net intact.
*
* However, we expect that these deltas will occasionally be too large
* to fit in a typical workstation's swap area. For example, in
* checking out a 200Mb source tree, the entire source tree is
* represented by a single tree delta. So it's important to handle
* deltas that are too large to fit in swap all at once.
*
* So instead of representing the tree delta explicitly, we define a
* standard way for a consumer to process each piece of a tree delta
* as soon as the producer creates it. The svn_delta_editor_t
* structure is a set of callback functions to be defined by a delta
* consumer,