diff options
Diffstat (limited to 'subversion/include/private/svn_branch.h')
| -rw-r--r-- | subversion/include/private/svn_branch.h | 679 |
1 files changed, 679 insertions, 0 deletions
diff --git a/subversion/include/private/svn_branch.h b/subversion/include/private/svn_branch.h new file mode 100644 index 000000000000..3fbaeb7ef77c --- /dev/null +++ b/subversion/include/private/svn_branch.h @@ -0,0 +1,679 @@ +/** + * @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 */ |