[Subversion Wiki] Update of "Ev2" by HyrumWright

[Apache subversion Wiki <co...@subversion.apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Subversion Wiki" for change notification.

The "Ev2" page has been changed by HyrumWright:
http://wiki.apache.org/subversion/Ev2

Comment:
New, with a bit of context from svn_editor.h and a link to the implementation plan.

New page:
== Ev2 ==

''The following is taken from [[http://svn.apache.org/repos/asf/subversion/trunk/subversion/include/svn_editor.h|svn_editor.h]], which see for more thorough and current information.''

=== Transforming Trees ("editing") ===

In Subversion, we have a number of occasions where we transform a tree from one state into another. This process is called "editing" a tree.

In processing a `commit' command:
 * The client examines its working copy data to determine the set of changes necessary to transform its base tree into the desired target.
 * The client networking library delivers that set of changes/operations across the wire as an equivalent series of network requests (for example, to svnserve as an ra_svn protocol stream, or to an Apache httpd server as WebDAV commands)
 * The server receives those requests and applies the sequence of operations on a revision, producing a transaction representing the desired target.
 * The Subversion server then commits the transaction to the filesystem.

In processing an `update' command, the process is reversed:
 * The Subversion server module talks to the filesystem and computes a set of changes necessary to bring the client's working copy up to date.
 * The server serializes this description of changes, and delivers it to the client.
 * The client networking library receives that reply, producing a set of changes/operations to alter the working copy into the revision requested by the update command.
 * The working copy library applies those operations to the working copy to align it with the requested update target.

The series of changes (or operations) necessary to transform a tree from one state into another is passed between subsystems using this "editor" interface. The "receiver" edits its tree according to the operations described by the "driver".

Note that the driver must have a perfect understanding of the tree which the receiver will be applying edits upon. There is no room for error here, and the interface embodies assumptions/requirements that the driver has about the targeted tree. As a result, this interface is a standardized mechanism of *describing* those change operations, but the intimate knowledge between the driver and the receiver implies some level of coupling between those subsystems.

The set of changes, and the data necessary to describe it entirely, is completely unbounded. An addition of one simple 20 GB file might be well past the available memory of a machine processing these operations. As a result, the API to describe the changes is designed to be applied in a sequential (and relatively random-access) model. The operations can be streamed from the driver to the receiver, resulting in the receiver editing its tree to the target state defined by the driver.

=== History ===
Classically, Subversion had a notion of a "tree delta" which could be passed around as an independent entity. Theory implied this delta was an entity in its own right, to be used when and where necessary. Unfortunately, this theory did not work well in practice. The producer and consumer of these tree deltas were (and are) tightly coupled. As noted above, the tree delta producer needed to be *totally* aware of the tree that it needed to edit. So rather than telling the delta consumer how to edit its tree, the classic #svn_delta_editor_t interface focused entirely on the tree delta, an intermediate (logical) data structure which was unusable outside of the particular, coupled pairing of producer and consumer. This generation of the API forgoes the logical tree delta entity and directly passes the necessary edits/changes/operations from the producer to the consumer. In our new parlance, one subsystem "drives" a set of operations describing the change, and a "receiver" accepts and applies them to its tree.

The classic interface was named #svn_delta_editor_t and was described idiomatically as the "editor interface". This generation of the interface retains the "editor" name for that reason. All notions of a "tree delta" structure are no longer part of this interface.

The old interface was purely vtable-based and used a number of special editors which could be interposed between the driver and receiver. Those editors provided cancellation, debugging, and other various operations. While the "interposition" pattern is still possible with this interface, the most common functionality (cancellation and debugging) have been integrated directly into this new editor system.

=== Implementation Plan ===

See the [[Ev2ImplementationPlan|Ev2 implementation plan]] for current status and future implementation plans.