subversion/include/private/svn_branch.h - subversion - Git at Google

 /**
  * @copyright
  * ====================================================================
  *    Licensed to the Apache Software Foundation (ASF) under one
  *    or more contributor license agreements.  See the NOTICE file
  *    distributed with this work for additional information
  *    regarding copyright ownership.  The ASF licenses this file
  *    to you under the Apache License, Version 2.0 (the
  *    "License"); you may not use this file except in compliance
  *    with the License.  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  *    Unless required by applicable law or agreed to in writing,
  *    software distributed under the License is distributed on an
  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  *    KIND, either express or implied.  See the License for the
  *    specific language governing permissions and limitations
  *    under the License.
  * ====================================================================
  * @endcopyright
  *
  * @file svn_branch.h
  * @brief Operating on a branched version history
  *
  * @since New in ???.
  */

 /* 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__txn_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_branch__txn_sequence_point' method.
  */


 #ifndef SVN_BRANCH_H
 #define SVN_BRANCH_H

 #include <apr_pools.h>

 #include "svn_types.h"
 #include "svn_error.h"
 #include "svn_io.h"    /* for svn_stream_t  */
 #include "svn_delta.h"

 #include "private/svn_element.h"

 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */


 /* ### */
 #define SVN_BRANCH__ERR 123456

 /** Element Identifier (EID).
  *
  * An element may appear in any or all branches, and its EID is the same in
  * each branch in which the element appears.
  *
  * By definition, an element keeps the same EID for its whole lifetime, even
  * if deleted from all branches and later 'resurrected'.
  *
  * In principle, an EID is an arbitrary token and has no intrinsic
  * relationships (except equality) to other EIDs. The current implementation
  * uses integers and allocates them sequentially from a central counter, but
  * the implementation may be changed.
  *
  * ### In most places the code currently says 'int', verbatim.
  */
 typedef int svn_branch__eid_t;

 typedef struct svn_branch__el_rev_id_t svn_branch__el_rev_id_t;

 typedef struct svn_branch__rev_bid_eid_t svn_branch__rev_bid_eid_t;

 typedef struct svn_branch__rev_bid_t svn_branch__rev_bid_t;

 typedef struct svn_branch__state_t svn_branch__state_t;

 /* Per-repository branching info.
  */
 typedef struct svn_branch__repos_t svn_branch__repos_t;

 /* Methods (conceptually public, but called indirectly) for a transaction.
  */
 typedef struct svn_branch__txn_vtable_t svn_branch__txn_vtable_t;

 /* Private data for a transaction.
  */
 typedef struct svn_branch__txn_priv_t svn_branch__txn_priv_t;

 /* A container for all the branching metadata for a specific revision (or
  * an uncommitted transaction).
  */
 typedef struct svn_branch__txn_t
 {
   /* Methods (conceptually public, but called indirectly). */
   svn_branch__txn_vtable_t *vtable;

   /* Private data. */
   svn_branch__txn_priv_t *priv;

   /* Public data. */

   /* The repository in which this revision exists. */
   svn_branch__repos_t *repos;

   /* If committed, the revision number; else SVN_INVALID_REVNUM. */
   svn_revnum_t rev;

   /* If committed, the previous revision number, else the revision number
      on which this transaction is based. */
   svn_revnum_t base_rev;

 } svn_branch__txn_t;

 /* Create a new branch txn object.
  */
 svn_branch__txn_t *
 svn_branch__txn_create(const svn_branch__txn_vtable_t *vtable,
                        svn_cancel_func_t cancel_func,
                        void *cancel_baton,
                        apr_pool_t *result_pool);

 /* Return all the branches in TXN.
  *
  * These branches are available for reading. (Some of them may also be
  * mutable.)
  *
  * ### Rename to 'list_branches' & return only their ids?
  *
  * Return an empty array if there are none.
  */
 apr_array_header_t *
 svn_branch__txn_get_branches(const svn_branch__txn_t *txn,
                              apr_pool_t *result_pool);

 /* Return the branch whose id is BRANCH_ID in TXN.
  *
  * Return NULL if not found.
  *
  * Note: a branch id is, in behavioural terms, an arbitrary token. In the
  * current implementation it is constructed from the hierarchy of subbranch
  * root EIDs leading to the branch, but that may be changed in future.
  *
  * See also: svn_branch__get_id().
  */
 svn_branch__state_t *
 svn_branch__txn_get_branch_by_id(const svn_branch__txn_t *txn,
                                  const char *branch_id,
                                  apr_pool_t *scratch_pool);

 svn_error_t *
 svn_branch__txn_get_num_new_eids(const svn_branch__txn_t *txn,
                                  int *num_new_eids_p,
                                  apr_pool_t *scratch_pool);

 /* Assign a new txn-scope element id in TXN.
  */
 svn_error_t *
 svn_branch__txn_new_eid(svn_branch__txn_t *txn,
                         int *new_eid_p,
                         apr_pool_t *scratch_pool);

 /** Open for writing, either a new branch or an existing branch.
  *
  * When creating a new branch, declare its root element id to be ROOT_EID. Do
  * not instantiate the root element, nor any other elements.
  *
  * TREE_REF specifies the initial tree content, by reference to a committed
  * tree. It overwrites any existing tree, even if the branch was already
  * mutable in the txn.
  *
  * If TREE_REF is null, then the initial tree is empty for a new branch
  * (not already present in the txn), or the branch's current tree if the
  * branch was already present (readable or mutable) in the txn.
  *
  * ### TODO: Take a 'history' parameter; 'none' is a valid option.
  *
  * We use a common 'open subbranch' method for both 'find' and 'add'
  * cases, according to the principle that 'editing' a txn should dictate
  * the new state without reference to the old state.
  *
  * This method returns a mutable 'branch state' object which is a part of
  * the txn.
  *
  * ### When opening ('finding') an existing branch, ROOT_EID should match
  *     it. (Should we check, and throw an error if not?)
  */
 svn_error_t *
 svn_branch__txn_open_branch(svn_branch__txn_t *txn,
                             svn_branch__state_t **new_branch_p,
                             const char *branch_id,
                             int root_eid,
                             svn_branch__rev_bid_eid_t *tree_ref,
                             apr_pool_t *result_pool,
                             apr_pool_t *scratch_pool);

 /** Register a sequence point.
  *
  * At a sequence point, elements are arranged in a tree hierarchy: each
  * element has exactly one parent element, except the root, and so on.
  * Translation between paths and element addressing is defined only at
  * a sequence point.
  *
  * The other edit operations -- add, alter, delete, etc. -- result in a
  * state that is not a sequence point.
  *
  * The new transaction begins at a sequence point. Completion of editing
  * (svn_branch__txn_complete()) also creates a sequence point.
  */
 svn_error_t *
 svn_branch__txn_sequence_point(svn_branch__txn_t *txn,
                                apr_pool_t *scratch_pool);

 /** Finalize this transaction.
  *
  * Notify that the edit has been completed successfully.
  */
 svn_error_t *
 svn_branch__txn_complete(svn_branch__txn_t *txn,
                          apr_pool_t *scratch_pool);

 /** Abandon this transaction.
  *
  * Notify that editing this transaction was not successful.
  */
 svn_error_t *
 svn_branch__txn_abort(svn_branch__txn_t *txn,
                       apr_pool_t *scratch_pool);

 /* Change txn-local EIDs (negative integers) in TXN to revision EIDs, by
  * assigning a new revision-EID (positive integer) for each one.
  *
  * Rewrite TXN->first_eid and TXN->next_eid accordingly.
  */
 svn_error_t *
 svn_branch__txn_finalize_eids(svn_branch__txn_t *txn,
                               apr_pool_t *scratch_pool);

 /* Often, branches have the same root element. For example,
  * branching /trunk to /branches/br1 results in:
  *
  *      branch 1: (root-EID=100)
  *          EID 100 => /trunk
  *          ...
  *      branch 2: (root-EID=100)
  *          EID 100 => /branches/br1
  *          ...
  *
  * However, the root element of one branch may correspond to a non-root
  * element of another branch.
  *
  * Continuing the same example, branching from the trunk subtree
  * /trunk/D (which is not itself a branch root) results in:
  *
  *      branch 3: (root-EID=104)
  *          EID 100 => (nil)
  *          ...
  *          EID 104 => /branches/branch-of-trunk-subtree-D
  *          ...
  */

 /* Methods (conceptually public, but called indirectly) for a branch state.
  */
 typedef struct svn_branch__state_vtable_t svn_branch__state_vtable_t;

 /* Private data for a branch state.
  */
 typedef struct svn_branch__state_priv_t svn_branch__state_priv_t;

 /* A branch state.
  *
  * A branch state object describes one version of one branch.
  */
 struct svn_branch__state_t
 {
   /* Methods (conceptually public, but called indirectly). */
   svn_branch__state_vtable_t *vtable;

   /* Private data. */
   svn_branch__state_priv_t *priv;

   /* Public data. */

   /* The branch identifier (starting with 'B') */
   const char *bid;

   /* The revision to which this branch state belongs */
   /* ### Later we should remove this and let a single state be sharable
      by multiple txns. */
   svn_branch__txn_t *txn;

 };

 /* Create a new branch state object.
  */
 svn_branch__state_t *
 svn_branch__state_create(const svn_branch__state_vtable_t *vtable,
                          svn_cancel_func_t cancel_func,
                          void *cancel_baton,
                          apr_pool_t *result_pool);

 /* Get the full id of branch BRANCH.
  *
  * Branch id format:
  *      B<top-level-branch-num>[.<1st-level-eid>[.<2nd-level-eid>[...]]]
  *
  * Note: a branch id is, in behavioural terms, an arbitrary token. In the
  * current implementation it is constructed from the hierarchy of subbranch
  * root EIDs leading to the branch, but that may be changed in future.
  *
  * See also: svn_branch__txn_get_branch_by_id().
  */
 const char *
 svn_branch__get_id(const svn_branch__state_t *branch,
                    apr_pool_t *result_pool);

 /* Return the element id of the root element of BRANCH.
  */
 int
 svn_branch__root_eid(const svn_branch__state_t *branch);

 /* Return the id of the branch nested in OUTER_BID at element OUTER_EID.
  *
  * For a top-level branch, OUTER_BID is null and OUTER_EID is the
  * top-level branch number.
  *
  * (Such branches need not exist. This works purely with ids, making use
  * of the fact that nested branch ids are predictable based on the nesting
  * element id.)
  */
 const char *
 svn_branch__id_nest(const char *outer_bid,
                     int outer_eid,
                     apr_pool_t *result_pool);

 /* Given a nested branch id BID, set *OUTER_BID to the outer branch's id
  * and *OUTER_EID to the nesting element in the outer branch.
  *
  * For a top-level branch, set *OUTER_BID to NULL and *OUTER_EID to the
  * top-level branch number.
  *
  * (Such branches need not exist. This works purely with ids, making use
  * of the fact that nested branch ids are predictable based on the nesting
  * element id.)
  */
 void
 svn_branch__id_unnest(const char **outer_bid,
                       int *outer_eid,
                       const char *bid,
                       apr_pool_t *result_pool);

 /* Remove the branch with id BID from the list of branches in TXN.
  */
 svn_error_t *
 svn_branch__txn_delete_branch(svn_branch__txn_t *txn,
                               const char *bid,
                               apr_pool_t *scratch_pool);

 /* Branch-Element-Revision */
 struct svn_branch__el_rev_id_t
 {
   /* The branch state that applies to REV. */
   svn_branch__state_t *branch;
   /* Element. */
   int eid;
   /* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'.
      ### Do we need this if BRANCH refers to a particular branch-revision? */
   svn_revnum_t rev;

 };

 /* Revision-branch-element id. */
 struct svn_branch__rev_bid_eid_t
 {
   /* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'. */
   svn_revnum_t rev;
   /* The branch id in revision REV. */
   const char *bid;
   /* Element id. */
   int eid;

 };

 /* Revision-branch id. */
 struct svn_branch__rev_bid_t
 {
   /* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'. */
   svn_revnum_t rev;
   /* The branch id in revision REV. */
   const char *bid;

 };

 /* Return a new el_rev_id object constructed with *shallow* copies of BRANCH,
  * EID and REV, allocated in RESULT_POOL.
  */
 svn_branch__el_rev_id_t *
 svn_branch__el_rev_id_create(svn_branch__state_t *branch,
                              int eid,
                              svn_revnum_t rev,
                              apr_pool_t *result_pool);

 /* Return a new id object constructed with a deep copy of OLD_ID,
  * allocated in RESULT_POOL. */
 svn_branch__el_rev_id_t *
 svn_branch__el_rev_id_dup(const svn_branch__el_rev_id_t *old_id,
                           apr_pool_t *result_pool);

 /* Return a new id object constructed with deep copies of REV, BRANCH_ID
  * and EID, allocated in RESULT_POOL.
  */
 svn_branch__rev_bid_eid_t *
 svn_branch__rev_bid_eid_create(svn_revnum_t rev,
                                const char *branch_id,
                                int eid,
                                apr_pool_t *result_pool);
 svn_branch__rev_bid_t *
 svn_branch__rev_bid_create(svn_revnum_t rev,
                            const char *branch_id,
                            apr_pool_t *result_pool);

 /* Return a new id object constructed with a deep copy of OLD_ID,
  * allocated in RESULT_POOL. */
 svn_branch__rev_bid_eid_t *
 svn_branch__rev_bid_eid_dup(const svn_branch__rev_bid_eid_t *old_id,
                             apr_pool_t *result_pool);
 svn_branch__rev_bid_t *
 svn_branch__rev_bid_dup(const svn_branch__rev_bid_t *old_id,
                         apr_pool_t *result_pool);

 svn_boolean_t
 svn_branch__rev_bid_equal(const svn_branch__rev_bid_t *id1,
                           const svn_branch__rev_bid_t *id2);

 typedef struct svn_branch__history_t
 {
   /* The immediate parents of this state in the branch/merge graph.
      Hash of (BID -> svn_branch__rev_bid_t). */
   apr_hash_t *parents;
 } svn_branch__history_t;

 svn_branch__history_t *
 svn_branch__history_create_empty(apr_pool_t *result_pool);

 svn_branch__history_t *
 svn_branch__history_create(apr_hash_t *parents,
                            apr_pool_t *result_pool);

 svn_branch__history_t *
 svn_branch__history_dup(const svn_branch__history_t *old,
                         apr_pool_t *result_pool);

 /* Return the mapping of elements in branch BRANCH.
  */
 svn_error_t *
 svn_branch__state_get_elements(const svn_branch__state_t *branch,
                                svn_element__tree_t **element_tree_p,
                                apr_pool_t *result_pool);

 /* In BRANCH, get element EID (parent, name, payload).
  *
  * If element EID is not present, return null.
  */
 svn_error_t *
 svn_branch__state_get_element(const svn_branch__state_t *branch,
                               svn_element__content_t **element_p,
                               int eid,
                               apr_pool_t *result_pool);

 /** Equivalent to
  *    alter_one(..., element->parent_eid, element->name, element->payload),
  * or, if @a element is null, to
  *    delete_one(...).
  */
 svn_error_t *
 svn_branch__state_set_element(svn_branch__state_t *branch,
                               int eid,
                               const svn_element__content_t *element,
                               apr_pool_t *result_pool);

 /** Specify that the element of @a branch identified by @a eid shall not
  * be present.
  *
  * The delete is not explicitly recursive. However, as an effect of the
  * final 'flattening' of a branch state into a single tree, each element
  * in the final state that still has this element as its parent will also
  * be deleted, recursively.
  *
  * The element @a eid must not be the root element of @a branch.
  *
  * ### Options for Out-Of-Date Checking on Rebase
  *
  *   We may want to specify what kind of OOD check takes place. The
  *   following two options differ in what happens to an element that is
  *   added, on the other side, as a child of this deleted element.
  *
  *   Rebase option 1: The rebase checks for changes in the whole subtree,
  *   excluding any portions of the subtree for which an explicit delete or
  *   move-away has been issued. The check includes checking that the other
  *   side has not added any child. In other words, the deletion is
  *   interpreted as an action affecting a subtree (dynamically rooted at
  *   this element), rather than as an action affecting a single element or
  *   a fixed set of elements that was explicitly or implicitly specified
  *   by the sender.
  *
  *   To delete a mixed-rev subtree, the client sends an explicit delete for
  *   each subtree that has a different base revision from its parent.
  *
  *   Rebase option 2: The rebase checks for changes to this element only.
  *   The sender can send an explicit delete for each existing child element
  *   that it requires to be checked as well. However, there is no way for
  *   the sender to specify whether a child element added by the other side
  *   should be considered an out-of-date error or silently deleted.
  *
  *   It would also be possible to let the caller specify, at some suitable
  *   granularity, which option to use.
  */
 svn_error_t *
 svn_branch__state_delete_one(svn_branch__state_t *branch,
                              svn_branch__eid_t eid,
                              apr_pool_t *scratch_pool);

 /** Specify the tree position and payload of the element of @a branch
  * identified by @a eid.
  *
  * Set the element's parent EID, name and payload to @a new_parent_eid,
  * @a new_name and @a new_payload respectively.
  *
  * This may create a new element or alter an existing element.
  *
  * If the element ...                   we can describe the effect as ...
  *
  *   exists in the branch               =>  altering it;
  *   previously existed in the branch   =>  resurrecting it;
  *   only existed in other branches     =>  branching it;
  *   never existed anywhere             =>  creating or adding it.
  *
  * However, these are imprecise descriptions and not mutually exclusive.
  * For example, if it existed previously in this branch and another, then
  * we may describe the result as 'resurrecting' and/or as 'branching'.
  *
  * Duplicate @a new_name and @a new_payload into the branch's pool.
  */
 svn_error_t *
 svn_branch__state_alter_one(svn_branch__state_t *branch,
                             svn_branch__eid_t eid,
                             svn_branch__eid_t new_parent_eid,
                             const char *new_name,
                             const svn_element__payload_t *new_payload,
                             apr_pool_t *scratch_pool);

 svn_error_t *
 svn_branch__state_copy_tree(svn_branch__state_t *branch,
                             const svn_branch__rev_bid_eid_t *src_el_rev,
                             svn_branch__eid_t new_parent_eid,
                             const char *new_name,
                             apr_pool_t *scratch_pool);

 /* Purge orphaned elements in BRANCH.
  */
 svn_error_t *
 svn_branch__state_purge(svn_branch__state_t *branch,
                         apr_pool_t *scratch_pool);

 /* Get the merge history of BRANCH.
  */
 svn_error_t *
 svn_branch__state_get_history(svn_branch__state_t *branch,
                               svn_branch__history_t **merge_history_p,
                               apr_pool_t *result_pool);

 /* Set the merge history of BRANCH.
  */
 svn_error_t *
 svn_branch__state_set_history(svn_branch__state_t *branch,
                               const svn_branch__history_t *merge_history,
                               apr_pool_t *scratch_pool);

 /* Return the branch-relative path of element EID in BRANCH.
  *
  * If the element EID does not currently exist in BRANCH, return NULL.
  *
  * ### TODO: Clarify sequencing requirements.
  */
 const char *
 svn_branch__get_path_by_eid(const svn_branch__state_t *branch,
                             int eid,
                             apr_pool_t *result_pool);

 /* Return the EID for the branch-relative path PATH in BRANCH.
  *
  * If no element of BRANCH is at this path, return -1.
  *
  * ### TODO: Clarify sequencing requirements.
  */
 int
 svn_branch__get_eid_by_path(const svn_branch__state_t *branch,
                             const char *path,
                             apr_pool_t *scratch_pool);

 /* Get the default branching metadata for r0 of a new repository.
  */
 svn_string_t *
 svn_branch__get_default_r0_metadata(apr_pool_t *result_pool);

 /* Create a new txn object *TXN_P, initialized with info
  * parsed from STREAM, allocated in RESULT_POOL.
  */
 svn_error_t *
 svn_branch__txn_parse(svn_branch__txn_t **txn_p,
                       svn_branch__repos_t *repos,
                       svn_stream_t *stream,
                       apr_pool_t *result_pool,
                       apr_pool_t *scratch_pool);

 /* Write to STREAM a parseable representation of TXN.
  */
 svn_error_t *
 svn_branch__txn_serialize(svn_branch__txn_t *txn,
                           svn_stream_t *stream,
                           apr_pool_t *scratch_pool);

 /* Write to STREAM a parseable representation of BRANCH.
  */
 svn_error_t *
 svn_branch__state_serialize(svn_stream_t *stream,
                             svn_branch__state_t *branch,
                             apr_pool_t *scratch_pool);


 #ifdef __cplusplus
 }
 #endif /* __cplusplus */

 #endif /* SVN_BRANCH_H */
	/**
	* @copyright
	* ====================================================================
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	* ====================================================================
	* @endcopyright
	*
	* @file svn_branch.h
	* @brief Operating on a branched version history
	*
	* @since New in ???.
	*/

	/* 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__txn_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_branch__txn_sequence_point' method.
	*/


	#ifndef SVN_BRANCH_H
	#define SVN_BRANCH_H

	#include <apr_pools.h>

	#include "svn_types.h"
	#include "svn_error.h"
	#include "svn_io.h" /* for svn_stream_t */
	#include "svn_delta.h"

	#include "private/svn_element.h"

	#ifdef __cplusplus
	extern "C" {
	#endif /* __cplusplus */


	/* ### */
	#define SVN_BRANCH__ERR 123456

	/** Element Identifier (EID).
	*
	* An element may appear in any or all branches, and its EID is the same in
	* each branch in which the element appears.
	*
	* By definition, an element keeps the same EID for its whole lifetime, even
	* if deleted from all branches and later 'resurrected'.
	*
	* In principle, an EID is an arbitrary token and has no intrinsic
	* relationships (except equality) to other EIDs. The current implementation
	* uses integers and allocates them sequentially from a central counter, but
	* the implementation may be changed.
	*
	* ### In most places the code currently says 'int', verbatim.
	*/
	typedef int svn_branch__eid_t;

	typedef struct svn_branch__el_rev_id_t svn_branch__el_rev_id_t;

	typedef struct svn_branch__rev_bid_eid_t svn_branch__rev_bid_eid_t;

	typedef struct svn_branch__rev_bid_t svn_branch__rev_bid_t;

	typedef struct svn_branch__state_t svn_branch__state_t;

	/* Per-repository branching info.
	*/
	typedef struct svn_branch__repos_t svn_branch__repos_t;

	/* Methods (conceptually public, but called indirectly) for a transaction.
	*/
	typedef struct svn_branch__txn_vtable_t svn_branch__txn_vtable_t;

	/* Private data for a transaction.
	*/
	typedef struct svn_branch__txn_priv_t svn_branch__txn_priv_t;

	/* A container for all the branching metadata for a specific revision (or
	* an uncommitted transaction).
	*/
	typedef struct svn_branch__txn_t
	{
	/* Methods (conceptually public, but called indirectly). */
	svn_branch__txn_vtable_t *vtable;

	/* Private data. */
	svn_branch__txn_priv_t *priv;

	/* Public data. */

	/* The repository in which this revision exists. */
	svn_branch__repos_t *repos;

	/* If committed, the revision number; else SVN_INVALID_REVNUM. */
	svn_revnum_t rev;

	/* If committed, the previous revision number, else the revision number
	on which this transaction is based. */
	svn_revnum_t base_rev;

	} svn_branch__txn_t;

	/* Create a new branch txn object.
	*/
	svn_branch__txn_t *
	svn_branch__txn_create(const svn_branch__txn_vtable_t *vtable,
	svn_cancel_func_t cancel_func,
	void *cancel_baton,
	apr_pool_t *result_pool);

	/* Return all the branches in TXN.
	*
	* These branches are available for reading. (Some of them may also be
	* mutable.)
	*
	* ### Rename to 'list_branches' & return only their ids?
	*
	* Return an empty array if there are none.
	*/
	apr_array_header_t *
	svn_branch__txn_get_branches(const svn_branch__txn_t *txn,
	apr_pool_t *result_pool);

	/* Return the branch whose id is BRANCH_ID in TXN.
	*
	* Return NULL if not found.
	*
	* Note: a branch id is, in behavioural terms, an arbitrary token. In the
	* current implementation it is constructed from the hierarchy of subbranch
	* root EIDs leading to the branch, but that may be changed in future.
	*
	* See also: svn_branch__get_id().
	*/
	svn_branch__state_t *
	svn_branch__txn_get_branch_by_id(const svn_branch__txn_t *txn,
	const char *branch_id,
	apr_pool_t *scratch_pool);

	svn_error_t *
	svn_branch__txn_get_num_new_eids(const svn_branch__txn_t *txn,
	int *num_new_eids_p,
	apr_pool_t *scratch_pool);

	/* Assign a new txn-scope element id in TXN.
	*/
	svn_error_t *
	svn_branch__txn_new_eid(svn_branch__txn_t *txn,
	int *new_eid_p,
	apr_pool_t *scratch_pool);

	/** Open for writing, either a new branch or an existing branch.
	*
	* When creating a new branch, declare its root element id to be ROOT_EID. Do
	* not instantiate the root element, nor any other elements.
	*
	* TREE_REF specifies the initial tree content, by reference to a committed
	* tree. It overwrites any existing tree, even if the branch was already
	* mutable in the txn.
	*
	* If TREE_REF is null, then the initial tree is empty for a new branch
	* (not already present in the txn), or the branch's current tree if the
	* branch was already present (readable or mutable) in the txn.
	*
	* ### TODO: Take a 'history' parameter; 'none' is a valid option.
	*
	* We use a common 'open subbranch' method for both 'find' and 'add'
	* cases, according to the principle that 'editing' a txn should dictate
	* the new state without reference to the old state.
	*
	* This method returns a mutable 'branch state' object which is a part of
	* the txn.
	*
	* ### When opening ('finding') an existing branch, ROOT_EID should match
	* it. (Should we check, and throw an error if not?)
	*/
	svn_error_t *
	svn_branch__txn_open_branch(svn_branch__txn_t *txn,
	svn_branch__state_t **new_branch_p,
	const char *branch_id,
	int root_eid,
	svn_branch__rev_bid_eid_t *tree_ref,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	/** Register a sequence point.
	*
	* At a sequence point, elements are arranged in a tree hierarchy: each
	* element has exactly one parent element, except the root, and so on.
	* Translation between paths and element addressing is defined only at
	* a sequence point.
	*
	* The other edit operations -- add, alter, delete, etc. -- result in a
	* state that is not a sequence point.
	*
	* The new transaction begins at a sequence point. Completion of editing
	* (svn_branch__txn_complete()) also creates a sequence point.
	*/
	svn_error_t *
	svn_branch__txn_sequence_point(svn_branch__txn_t *txn,
	apr_pool_t *scratch_pool);

	/** Finalize this transaction.
	*
	* Notify that the edit has been completed successfully.
	*/
	svn_error_t *
	svn_branch__txn_complete(svn_branch__txn_t *txn,
	apr_pool_t *scratch_pool);

	/** Abandon this transaction.
	*
	* Notify that editing this transaction was not successful.
	*/
	svn_error_t *
	svn_branch__txn_abort(svn_branch__txn_t *txn,
	apr_pool_t *scratch_pool);

	/* Change txn-local EIDs (negative integers) in TXN to revision EIDs, by
	* assigning a new revision-EID (positive integer) for each one.
	*
	* Rewrite TXN->first_eid and TXN->next_eid accordingly.
	*/
	svn_error_t *
	svn_branch__txn_finalize_eids(svn_branch__txn_t *txn,
	apr_pool_t *scratch_pool);

	/* Often, branches have the same root element. For example,
	* branching /trunk to /branches/br1 results in:
	*
	* branch 1: (root-EID=100)
	* EID 100 => /trunk
	* ...
	* branch 2: (root-EID=100)
	* EID 100 => /branches/br1
	* ...
	*
	* However, the root element of one branch may correspond to a non-root
	* element of another branch.
	*
	* Continuing the same example, branching from the trunk subtree
	* /trunk/D (which is not itself a branch root) results in:
	*
	* branch 3: (root-EID=104)
	* EID 100 => (nil)
	* ...
	* EID 104 => /branches/branch-of-trunk-subtree-D
	* ...
	*/

	/* Methods (conceptually public, but called indirectly) for a branch state.
	*/
	typedef struct svn_branch__state_vtable_t svn_branch__state_vtable_t;

	/* Private data for a branch state.
	*/
	typedef struct svn_branch__state_priv_t svn_branch__state_priv_t;

	/* A branch state.
	*
	* A branch state object describes one version of one branch.
	*/
	struct svn_branch__state_t
	{
	/* Methods (conceptually public, but called indirectly). */
	svn_branch__state_vtable_t *vtable;

	/* Private data. */
	svn_branch__state_priv_t *priv;

	/* Public data. */

	/* The branch identifier (starting with 'B') */
	const char *bid;

	/* The revision to which this branch state belongs */
	/* ### Later we should remove this and let a single state be sharable
	by multiple txns. */
	svn_branch__txn_t *txn;

	};

	/* Create a new branch state object.
	*/
	svn_branch__state_t *
	svn_branch__state_create(const svn_branch__state_vtable_t *vtable,
	svn_cancel_func_t cancel_func,
	void *cancel_baton,
	apr_pool_t *result_pool);

	/* Get the full id of branch BRANCH.
	*
	* Branch id format:
	* B<top-level-branch-num>[.<1st-level-eid>[.<2nd-level-eid>[...]]]
	*
	* Note: a branch id is, in behavioural terms, an arbitrary token. In the
	* current implementation it is constructed from the hierarchy of subbranch
	* root EIDs leading to the branch, but that may be changed in future.
	*
	* See also: svn_branch__txn_get_branch_by_id().
	*/
	const char *
	svn_branch__get_id(const svn_branch__state_t *branch,
	apr_pool_t *result_pool);

	/* Return the element id of the root element of BRANCH.
	*/
	int
	svn_branch__root_eid(const svn_branch__state_t *branch);

	/* Return the id of the branch nested in OUTER_BID at element OUTER_EID.
	*
	* For a top-level branch, OUTER_BID is null and OUTER_EID is the
	* top-level branch number.
	*
	* (Such branches need not exist. This works purely with ids, making use
	* of the fact that nested branch ids are predictable based on the nesting
	* element id.)
	*/
	const char *
	svn_branch__id_nest(const char *outer_bid,
	int outer_eid,
	apr_pool_t *result_pool);

	/* Given a nested branch id BID, set *OUTER_BID to the outer branch's id
	* and *OUTER_EID to the nesting element in the outer branch.
	*
	* For a top-level branch, set OUTER_BID to NULL and OUTER_EID to the
	* top-level branch number.
	*
	* (Such branches need not exist. This works purely with ids, making use
	* of the fact that nested branch ids are predictable based on the nesting
	* element id.)
	*/
	void
	svn_branch__id_unnest(const char **outer_bid,
	int *outer_eid,
	const char *bid,
	apr_pool_t *result_pool);

	/* Remove the branch with id BID from the list of branches in TXN.
	*/
	svn_error_t *
	svn_branch__txn_delete_branch(svn_branch__txn_t *txn,
	const char *bid,
	apr_pool_t *scratch_pool);

	/* Branch-Element-Revision */
	struct svn_branch__el_rev_id_t
	{
	/* The branch state that applies to REV. */
	svn_branch__state_t *branch;
	/* Element. */
	int eid;
	/* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'.
	### Do we need this if BRANCH refers to a particular branch-revision? */
	svn_revnum_t rev;

	};

	/* Revision-branch-element id. */
	struct svn_branch__rev_bid_eid_t
	{
	/* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'. */
	svn_revnum_t rev;
	/* The branch id in revision REV. */
	const char *bid;
	/* Element id. */
	int eid;

	};

	/* Revision-branch id. */
	struct svn_branch__rev_bid_t
	{
	/* Revision. SVN_INVALID_REVNUM means 'in this transaction', not 'head'. */
	svn_revnum_t rev;
	/* The branch id in revision REV. */
	const char *bid;

	};

	/* Return a new el_rev_id object constructed with shallow copies of BRANCH,
	* EID and REV, allocated in RESULT_POOL.
	*/
	svn_branch__el_rev_id_t *
	svn_branch__el_rev_id_create(svn_branch__state_t *branch,
	int eid,
	svn_revnum_t rev,
	apr_pool_t *result_pool);

	/* Return a new id object constructed with a deep copy of OLD_ID,
	* allocated in RESULT_POOL. */
	svn_branch__el_rev_id_t *
	svn_branch__el_rev_id_dup(const svn_branch__el_rev_id_t *old_id,
	apr_pool_t *result_pool);

	/* Return a new id object constructed with deep copies of REV, BRANCH_ID
	* and EID, allocated in RESULT_POOL.
	*/
	svn_branch__rev_bid_eid_t *
	svn_branch__rev_bid_eid_create(svn_revnum_t rev,
	const char *branch_id,
	int eid,
	apr_pool_t *result_pool);
	svn_branch__rev_bid_t *
	svn_branch__rev_bid_create(svn_revnum_t rev,
	const char *branch_id,
	apr_pool_t *result_pool);

	/* Return a new id object constructed with a deep copy of OLD_ID,
	* allocated in RESULT_POOL. */
	svn_branch__rev_bid_eid_t *
	svn_branch__rev_bid_eid_dup(const svn_branch__rev_bid_eid_t *old_id,
	apr_pool_t *result_pool);
	svn_branch__rev_bid_t *
	svn_branch__rev_bid_dup(const svn_branch__rev_bid_t *old_id,
	apr_pool_t *result_pool);

	svn_boolean_t
	svn_branch__rev_bid_equal(const svn_branch__rev_bid_t *id1,
	const svn_branch__rev_bid_t *id2);

	typedef struct svn_branch__history_t
	{
	/* The immediate parents of this state in the branch/merge graph.
	Hash of (BID -> svn_branch__rev_bid_t). */
	apr_hash_t *parents;
	} svn_branch__history_t;

	svn_branch__history_t *
	svn_branch__history_create_empty(apr_pool_t *result_pool);

	svn_branch__history_t *
	svn_branch__history_create(apr_hash_t *parents,
	apr_pool_t *result_pool);

	svn_branch__history_t *
	svn_branch__history_dup(const svn_branch__history_t *old,
	apr_pool_t *result_pool);

	/* Return the mapping of elements in branch BRANCH.
	*/
	svn_error_t *
	svn_branch__state_get_elements(const svn_branch__state_t *branch,
	svn_element__tree_t **element_tree_p,
	apr_pool_t *result_pool);

	/* In BRANCH, get element EID (parent, name, payload).
	*
	* If element EID is not present, return null.
	*/
	svn_error_t *
	svn_branch__state_get_element(const svn_branch__state_t *branch,
	svn_element__content_t **element_p,
	int eid,
	apr_pool_t *result_pool);

	/** Equivalent to
	* alter_one(..., element->parent_eid, element->name, element->payload),
	* or, if @a element is null, to
	* delete_one(...).
	*/
	svn_error_t *
	svn_branch__state_set_element(svn_branch__state_t *branch,
	int eid,
	const svn_element__content_t *element,
	apr_pool_t *result_pool);

	/** Specify that the element of @a branch identified by @a eid shall not
	* be present.
	*
	* The delete is not explicitly recursive. However, as an effect of the
	* final 'flattening' of a branch state into a single tree, each element
	* in the final state that still has this element as its parent will also
	* be deleted, recursively.
	*
	* The element @a eid must not be the root element of @a branch.
	*
	* ### Options for Out-Of-Date Checking on Rebase
	*
	* We may want to specify what kind of OOD check takes place. The
	* following two options differ in what happens to an element that is
	* added, on the other side, as a child of this deleted element.
	*
	* Rebase option 1: The rebase checks for changes in the whole subtree,
	* excluding any portions of the subtree for which an explicit delete or
	* move-away has been issued. The check includes checking that the other
	* side has not added any child. In other words, the deletion is
	* interpreted as an action affecting a subtree (dynamically rooted at
	* this element), rather than as an action affecting a single element or
	* a fixed set of elements that was explicitly or implicitly specified
	* by the sender.
	*
	* To delete a mixed-rev subtree, the client sends an explicit delete for
	* each subtree that has a different base revision from its parent.
	*
	* Rebase option 2: The rebase checks for changes to this element only.
	* The sender can send an explicit delete for each existing child element
	* that it requires to be checked as well. However, there is no way for
	* the sender to specify whether a child element added by the other side
	* should be considered an out-of-date error or silently deleted.
	*
	* It would also be possible to let the caller specify, at some suitable
	* granularity, which option to use.
	*/
	svn_error_t *
	svn_branch__state_delete_one(svn_branch__state_t *branch,
	svn_branch__eid_t eid,
	apr_pool_t *scratch_pool);

	/** Specify the tree position and payload of the element of @a branch
	* identified by @a eid.
	*
	* Set the element's parent EID, name and payload to @a new_parent_eid,
	* @a new_name and @a new_payload respectively.
	*
	* This may create a new element or alter an existing element.
	*
	* If the element ... we can describe the effect as ...
	*
	* exists in the branch => altering it;
	* previously existed in the branch => resurrecting it;
	* only existed in other branches => branching it;
	* never existed anywhere => creating or adding it.
	*
	* However, these are imprecise descriptions and not mutually exclusive.
	* For example, if it existed previously in this branch and another, then
	* we may describe the result as 'resurrecting' and/or as 'branching'.
	*
	* Duplicate @a new_name and @a new_payload into the branch's pool.
	*/
	svn_error_t *
	svn_branch__state_alter_one(svn_branch__state_t *branch,
	svn_branch__eid_t eid,
	svn_branch__eid_t new_parent_eid,
	const char *new_name,
	const svn_element__payload_t *new_payload,
	apr_pool_t *scratch_pool);

	svn_error_t *
	svn_branch__state_copy_tree(svn_branch__state_t *branch,
	const svn_branch__rev_bid_eid_t *src_el_rev,
	svn_branch__eid_t new_parent_eid,
	const char *new_name,
	apr_pool_t *scratch_pool);

	/* Purge orphaned elements in BRANCH.
	*/
	svn_error_t *
	svn_branch__state_purge(svn_branch__state_t *branch,
	apr_pool_t *scratch_pool);

	/* Get the merge history of BRANCH.
	*/
	svn_error_t *
	svn_branch__state_get_history(svn_branch__state_t *branch,
	svn_branch__history_t **merge_history_p,
	apr_pool_t *result_pool);

	/* Set the merge history of BRANCH.
	*/
	svn_error_t *
	svn_branch__state_set_history(svn_branch__state_t *branch,
	const svn_branch__history_t *merge_history,
	apr_pool_t *scratch_pool);

	/* Return the branch-relative path of element EID in BRANCH.
	*
	* If the element EID does not currently exist in BRANCH, return NULL.
	*
	* ### TODO: Clarify sequencing requirements.
	*/
	const char *
	svn_branch__get_path_by_eid(const svn_branch__state_t *branch,
	int eid,
	apr_pool_t *result_pool);

	/* Return the EID for the branch-relative path PATH in BRANCH.
	*
	* If no element of BRANCH is at this path, return -1.
	*
	* ### TODO: Clarify sequencing requirements.
	*/
	int
	svn_branch__get_eid_by_path(const svn_branch__state_t *branch,
	const char *path,
	apr_pool_t *scratch_pool);

	/* Get the default branching metadata for r0 of a new repository.
	*/
	svn_string_t *
	svn_branch__get_default_r0_metadata(apr_pool_t *result_pool);

	/* Create a new txn object *TXN_P, initialized with info
	* parsed from STREAM, allocated in RESULT_POOL.
	*/
	svn_error_t *
	svn_branch__txn_parse(svn_branch__txn_t **txn_p,
	svn_branch__repos_t *repos,
	svn_stream_t *stream,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	/* Write to STREAM a parseable representation of TXN.
	*/
	svn_error_t *
	svn_branch__txn_serialize(svn_branch__txn_t *txn,
	svn_stream_t *stream,
	apr_pool_t *scratch_pool);

	/* Write to STREAM a parseable representation of BRANCH.
	*/
	svn_error_t *
	svn_branch__state_serialize(svn_stream_t *stream,
	svn_branch__state_t *branch,
	apr_pool_t *scratch_pool);


	#ifdef __cplusplus
	}
	#endif /* __cplusplus */

	#endif /* SVN_BRANCH_H */