Author: julianfoad
Date: Thu Jun 4 16:52:35 2015
New Revision: 1683592
URL: http://svn.apache.org/r1683592
Log:
On the 'move-tracking-2' branch: Add notes about operating on transactions
and flat tree states.
* BRANCH-README,
subversion/include/private/svn_branch.h
Add notes about operating on transactions and flat trees, and what needs
to be done to improve the situation.
Modified:
subversion/branches/move-tracking-2/BRANCH-README
subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
Modified: subversion/branches/move-tracking-2/BRANCH-README
URL:
http://svn.apache.org/viewvc/subversion/branches/move-tracking-2/BRANCH-README?rev=1683592&r1=1683591&r2=1683592&view=diff
==============================================================================
--- subversion/branches/move-tracking-2/BRANCH-README (original)
+++ subversion/branches/move-tracking-2/BRANCH-README Thu Jun 4 16:52:35 2015
@@ -136,9 +136,34 @@ Work on this branch:
* The model.
To do:
- clarify the sequencing requirements of editing: for example,
+
+ - clarify the sequencing requirements of editing: for example,
requesting the full path to an element implies finalization of
at least it and all its parent elements
+
+ The editor currently includes a 'sequence_point' method.
+ This is a broken bit of design. It was an attempt to allow
+ 'flattening' the txn state into a tree on demand, so the client
+ (especially a client like svnmover) can query the txn by path.
+
+ The client should never make a query that involves paths on a
+ txn that is in an arbitrary state (some elements edited, some
+ yet to be edited).
+
+ The 'sequence_point' method should go away.
+ Instead, the client should request a (read-only) snapshot of
+ the state (e.g. svn_branch_subtree_t) at an appropriate time,
+ and query that.
+
+ Any 'svn_branch' APIs that look up by path or yield a path
+ should not be used on a txn in an arbitrary state, but only on
+ a 'flat' snapshot state (e.g. svn_branch_subtree_t).
+
+ Need to decide whether to use a single data type for both
+ txn and flat-tree, or separate types as currently done
+ ('svn_branch_state_t' and 'svn_branch_subtree_t'), and go
+ fully with whichever way we decide.
+
copying: model copying as a (tree) relationship between elements
that is the same across all branches in a family?
Modified:
subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
URL:
http://svn.apache.org/viewvc/subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h?rev=1683592&r1=1683591&r2=1683592&view=diff
==============================================================================
--- subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
(original)
+++ subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
Thu Jun 4 16:52:35 2015
@@ -26,6 +26,54 @@
* @since New in 1.10.
*/
+/* Transactions
+ *
+ * A 'txn' contains a set of changes to the branches/elements.
+ *
+ * To make changes you say, for example, "for element 5: I want the parent
+ * element to be 3 now, and its name to be 'bar', and its content to be
+ * {props=... text=...}". That sets up a move and/or rename and/or
+ * content-change (or possibly a no-op for all three aspects) for element 5.
+ *
+ * Before or after (or at the same time, if we make a parallelizable
+ * implementation) we can make edits to the other elements, including
+ * element 3.
+ *
+ * So at the time of the edit method 'change e5: let its parent be e3'
+ * we might or might not have even created e3, if that happens to be an
+ * element that we wish to create rather than one that already existed.
+ *
+ * We allow this non-ordering because we want the changes to different
+ * elements to be totally independent.
+ *
+ * So at any given 'moment' in time during specifying the changes to a
+ * txn, the txn state is not necessarily one that maps directly to a
+ * flat tree (single-rooted, no cycles, no clashes of paths, etc.).
+ *
+ * Once we've finished specifying the edits, then the txn state will be
+ * converted to a flat tree, and that's the final result. But we can't
+ * query an arbitrary txn (potentially in the middle of making changes
+ * to it) by path, because the paths are not fully defined yet.
+ *
+ * So there are three kinds of operations:
+ *
+ * - query involving paths
+ * => requires a flat tree state to query, not an in-progress txn
+ *
+ * - query, not involving paths
+ * => accepts a txn-in-progress or a flat tree
+ *
+ * - modify (not involving paths)
+ * => requires a txn
+ *
+ * Currently, a txn is represented by 'svn_branch_revision_root_t', with
+ * 'svn_branch_state_t' for the individual branches in it. A flat tree is
+ * represented by 'svn_branch_subtree_t'. But there is currently not a
+ * clean separation; there is some overlap and some warts such as the
+ * 'svn_editor3_sequence_point' method.
+ */
+
+
#ifndef SVN_BRANCH_H
#define SVN_BRANCH_H
