subversion/libsvn_fs_base/dag.h

   1 /* dag.h : DAG-like interface filesystem, private to libsvn_fs
   2  *
   3  * ====================================================================
   4  * Copyright (c) 2000-2006 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  */
  17
  18 #ifndef SVN_LIBSVN_FS_DAG_H
  19 #define SVN_LIBSVN_FS_DAG_H
  20
  21 #include "svn_fs.h"
  22
  23 #include "trail.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29 \f
  30 /* The interface in this file provides all the essential filesystem
  31    operations, but exposes the filesystem's DAG structure.  This makes
  32    it simpler to implement than the public interface, since a client
  33    of this interface has to understand and cope with shared structure
  34    directly as it appears in the database.  However, it's still a
  35    self-consistent set of invariants to maintain, making it
  36    (hopefully) a useful interface boundary.
  37
  38    In other words:
  39
  40    - The dag_node_t interface exposes the internal DAG structure of
  41      the filesystem, while the svn_fs.h interface does any cloning
  42      necessary to make the filesystem look like a tree.
  43
  44    - The dag_node_t interface exposes the existence of copy nodes,
  45      whereas the svn_fs.h handles them transparently.
  46
  47    - dag_node_t's must be explicitly cloned, whereas the svn_fs.h
  48      operations make clones implicitly.
  49
  50    - Callers of the dag_node_t interface use Berkeley DB transactions
  51      to ensure consistency between operations, while callers of the
  52      svn_fs.h interface use Subversion transactions.  */
  53
  54 \f
  55 /* Initializing a filesystem.  */
  56
  57
  58 /* Given a filesystem FS, which contains all the necessary tables,
  59    create the initial revision 0, and the initial root directory.  */
  60 svn_error_t *svn_fs_base__dag_init_fs(svn_fs_t *fs);
  61
  62
  63 \f
  64 /* Generic DAG node stuff.  */
  65
  66 typedef struct dag_node_t dag_node_t;
  67
  68
  69 /* Fill *NODE with a dag_node_t representing node revision ID in FS,
  70    allocating in POOL.  */
  71 svn_error_t *svn_fs_base__dag_get_node(dag_node_t **node,
  72                                        svn_fs_t *fs,
  73                                        const svn_fs_id_t *id,
  74                                        trail_t *trail,
  75                                        apr_pool_t *pool);
  76
  77
  78 /* Return a new dag_node_t object referring to the same node as NODE,
  79    allocated in POOL.  */
  80 dag_node_t *svn_fs_base__dag_dup(dag_node_t *node,
  81                                  apr_pool_t *pool);
  82
  83
  84 /* Return the filesystem containing NODE.  */
  85 svn_fs_t *svn_fs_base__dag_get_fs(dag_node_t *node);
  86
  87
  88 /* Set *REV to NODE's revision number, as part of TRAIL.  If NODE has
  89    never been committed as part of a revision, set *REV to
  90    SVN_INVALID_REVNUM.  */
  91 svn_error_t *svn_fs_base__dag_get_revision(svn_revnum_t *rev,
  92                                            dag_node_t *node,
  93                                            trail_t *trail,
  94                                            apr_pool_t *pool);
  95
  96
  97 /* Return the node revision ID of NODE.  The value returned is shared
  98    with NODE, and will be deallocated when NODE is.  */
  99 const svn_fs_id_t *svn_fs_base__dag_get_id(dag_node_t *node);
 100
 101
 102 /* Return the created path of NODE.  The value returned is shared
 103    with NODE, and will be deallocated when NODE is.  */
 104 const char *svn_fs_base__dag_get_created_path(dag_node_t *node);
 105
 106
 107 /* Set *ID_P to the node revision ID of NODE's immediate predecessor,
 108    or NULL if NODE has no predecessor, as part of TRAIL.  The returned
 109    ID will be allocated in POOL.  */
 110 svn_error_t *svn_fs_base__dag_get_predecessor_id(const svn_fs_id_t **id_p,
 111                                                  dag_node_t *node,
 112                                                  trail_t *trail,
 113                                                  apr_pool_t *pool);
 114
 115
 116 /* Set *COUNT to the number of predecessors NODE has (recursively), or
 117    -1 if not known, as part of TRAIL.  */
 118 svn_error_t *svn_fs_base__dag_get_predecessor_count(int *count,
 119                                                     dag_node_t *node,
 120                                                     trail_t *trail,
 121                                                     apr_pool_t *pool);
 122
 123
 124 /* Return non-zero IFF NODE is currently mutable under Subversion
 125    transaction TXN_ID.  */
 126 svn_boolean_t svn_fs_base__dag_check_mutable(dag_node_t *node,
 127                                              const char *txn_id);
 128
 129 /* Return the node kind of NODE. */
 130 svn_node_kind_t svn_fs_base__dag_node_kind(dag_node_t *node);
 131
 132 /* Set *PROPLIST_P to a PROPLIST hash representing the entire property
 133    list of NODE, as part of TRAIL.  The hash has const char * names
 134    (the property names) and svn_string_t * values (the property values).
 135
 136    If properties do not exist on NODE, *PROPLIST_P will be set to NULL.
 137
 138    The returned property list is allocated in POOL.  */
 139 svn_error_t *svn_fs_base__dag_get_proplist(apr_hash_t **proplist_p,
 140                                            dag_node_t *node,
 141                                            trail_t *trail,
 142                                            apr_pool_t *pool);
 143
 144 /* Set the property list of NODE to PROPLIST, as part of TRAIL.  The
 145    node being changed must be mutable.  TXN_ID is the Subversion
 146    transaction under which this occurs.  */
 147 svn_error_t *svn_fs_base__dag_set_proplist(dag_node_t *node,
 148                                            apr_hash_t *proplist,
 149                                            const char *txn_id,
 150                                            trail_t *trail,
 151                                            apr_pool_t *pool);
 152
 153
 154 \f
 155 /* Mergeinfo tracking stuff. */
 156
 157 /* If HAS_MERGEINFO is not null, set *HAS_MERGEINFO to TRUE iff NODE
 158    records that its property list contains merge tracking information.
 159
 160    If COUNT is not null, set *COUNT to the number of nodes --
 161    including NODE itself -- in the subtree rooted at NODE which claim
 162    to carry merge tracking information.
 163
 164    Do this as part of TRAIL, and use POOL for necessary allocations.
 165
 166    NOTE:  No validation against NODE's actual property list is
 167    performed. */
 168 svn_error_t *svn_fs_base__dag_get_mergeinfo_stats(svn_boolean_t *has_mergeinfo,
 169                                                   apr_int64_t *count,
 170                                                   dag_node_t *node,
 171                                                   trail_t *trail,
 172                                                   apr_pool_t *pool);
 173
 174 /* If HAS_MERGEINFO is set, record on NODE that its property list
 175    carries merge tracking information.  Otherwise, record on NODE its
 176    property list does *not* carry merge tracking information.  NODE
 177    must be mutable under TXN_ID (the Subversion transaction under
 178    which this operation occurs).  Set *HAD_MERGEINFO to the previous
 179    state of this record.
 180
 181    Update the mergeinfo count on NODE as necessary.
 182
 183    Do all of this as part of TRAIL, and use POOL for necessary
 184    allocations.
 185
 186    NOTE:  No validation against NODE's actual property list is
 187    performed. */
 188 svn_error_t *svn_fs_base__dag_set_has_mergeinfo(dag_node_t *node,
 189                                                 svn_boolean_t has_mergeinfo,
 190                                                 svn_boolean_t *had_mergeinfo,
 191                                                 const char *txn_id,
 192                                                 trail_t *trail,
 193                                                 apr_pool_t *pool);
 194
 195 /* Record on NODE a change of COUNT_DELTA nodes -- including NODE
 196    itself -- in the subtree rooted at NODE claim to carry merge
 197    tracking information.  That is, add COUNT_DELTA to NODE's current
 198    mergeinfo count (regardless of whether COUNT_DELTA is a positive or
 199    negative integer).
 200
 201    NODE must be mutable under TXN_ID (the Subversion transaction under
 202    which this operation occurs).  Do this as part of TRAIL, and use
 203    POOL for necessary allocations.
 204
 205    NOTE:  No validation of these claims is performed. */
 206 svn_error_t *svn_fs_base__dag_adjust_mergeinfo_count(dag_node_t *node,
 207                                                      apr_int64_t count_delta,
 208                                                      const char *txn_id,
 209                                                      trail_t *trail,
 210                                                      apr_pool_t *pool);
 211
 212 \f
 213 /* Revision and transaction roots.  */
 214
 215
 216 /* Open the root of revision REV of filesystem FS, as part of TRAIL.
 217    Set *NODE_P to the new node.  Allocate the node in POOL.  */
 218 svn_error_t *svn_fs_base__dag_revision_root(dag_node_t **node_p,
 219                                             svn_fs_t *fs,
 220                                             svn_revnum_t rev,
 221                                             trail_t *trail,
 222                                             apr_pool_t *pool);
 223
 224
 225 /* Set *NODE_P to the root of transaction TXN_ID in FS, as part
 226    of TRAIL.  Allocate the node in POOL.
 227
 228    Note that the root node of TXN_ID is not necessarily mutable.  If no
 229    changes have been made in the transaction, then it may share its
 230    root directory with its base revision.  To get a mutable root node
 231    for a transaction, call svn_fs_base__dag_clone_root.  */
 232 svn_error_t *svn_fs_base__dag_txn_root(dag_node_t **node_p,
 233                                        svn_fs_t *fs,
 234                                        const char *txn_id,
 235                                        trail_t *trail,
 236                                        apr_pool_t *pool);
 237
 238
 239 /* Set *NODE_P to the base root of transaction TXN_ID in FS, as part
 240    of TRAIL.  Allocate the node in POOL.  */
 241 svn_error_t *svn_fs_base__dag_txn_base_root(dag_node_t **node_p,
 242                                             svn_fs_t *fs,
 243                                             const char *txn_id,
 244                                             trail_t *trail,
 245                                             apr_pool_t *pool);
 246
 247
 248 /* Clone the root directory of TXN_ID in FS, and update the
 249    `transactions' table entry to point to it, unless this has been
 250    done already.  In either case, set *ROOT_P to a reference to the
 251    root directory clone.  Do all this as part of TRAIL, and allocate
 252    *ROOT_P in POOL.  */
 253 svn_error_t *svn_fs_base__dag_clone_root(dag_node_t **root_p,
 254                                          svn_fs_t *fs,
 255                                          const char *txn_id,
 256                                          trail_t *trail,
 257                                          apr_pool_t *pool);
 258
 259
 260 /* Commit the transaction TXN->id in TXN->FS, as part of TRAIL.  Store the
 261    new revision number in *NEW_REV.  This entails:
 262    - marking the tree of mutable nodes at TXN->id's root as immutable,
 263      and marking all their contents as stable
 264    - creating a new revision, with TXN->id's root as its root directory
 265    - promoting TXN->id to a "committed" transaction.
 266
 267    Beware!  This does not make sure that TXN->id is based on the very
 268    latest revision in TXN->FS.  If the caller doesn't take care of this,
 269    you may lose people's work!
 270
 271    Do any necessary temporary allocation in a subpool of POOL.
 272    Consume temporary space at most proportional to the maximum depth
 273    of SVN_TXN's tree of mutable nodes.  */
 274 svn_error_t *svn_fs_base__dag_commit_txn(svn_revnum_t *new_rev,
 275                                          svn_fs_txn_t *txn,
 276                                          trail_t *trail,
 277                                          apr_pool_t *pool);
 278
 279
 280 \f
 281 /* Directories.  */
 282
 283
 284 /* Open the node named NAME in the directory PARENT, as part of TRAIL.
 285    Set *CHILD_P to the new node, allocated in POOL.  NAME must be a
 286    single path component; it cannot be a slash-separated directory
 287    path.  */
 288 svn_error_t *svn_fs_base__dag_open(dag_node_t **child_p,
 289                                    dag_node_t *parent,
 290                                    const char *name,
 291                                    trail_t *trail,
 292                                    apr_pool_t *pool);
 293
 294
 295 /* Set *ENTRIES_P to a hash table of NODE's entries, as part of TRAIL,
 296    or NULL if NODE has no entries.  The keys of the table are entry
 297    names, and the values are svn_fs_dirent_t's.
 298
 299    The returned table is allocated in POOL.
 300
 301    NOTE: the 'kind' field of the svn_fs_dirent_t's is set to
 302    svn_node_unknown by this function -- callers that need in
 303    interesting value in these slots should fill them in using a new
 304    TRAIL, since the list of entries can be arbitrarily large.  */
 305 svn_error_t *svn_fs_base__dag_dir_entries(apr_hash_t **entries_p,
 306                                           dag_node_t *node,
 307                                           trail_t *trail,
 308                                           apr_pool_t *pool);
 309
 310
 311 /* Set ENTRY_NAME in NODE to point to ID, as part of TRAIL.  NODE must
 312    be a mutable directory.  ID can refer to a mutable or immutable
 313    node.  If ENTRY_NAME does not exist, it will be created.  TXN_ID is
 314    the Subversion transaction under which this occurs.*/
 315 svn_error_t *svn_fs_base__dag_set_entry(dag_node_t *node,
 316                                         const char *entry_name,
 317                                         const svn_fs_id_t *id,
 318                                         const char *txn_id,
 319                                         trail_t *trail,
 320                                         apr_pool_t *pool);
 321
 322
 323 /* Make a new mutable clone of the node named NAME in PARENT, and
 324    adjust PARENT's directory entry to point to it, as part of TRAIL,
 325    unless NAME in PARENT already refers to a mutable node.  In either
 326    case, set *CHILD_P to a reference to the new node, allocated in
 327    POOL.  PARENT must be mutable.  NAME must be a single path
 328    component; it cannot be a slash-separated directory path.
 329    PARENT_PATH must be the canonicalized absolute path of the parent
 330    directory.
 331
 332    COPY_ID, if non-NULL, is a key into the `copies' table, and
 333    indicates that this new node is being created as the result of a
 334    copy operation, and specifically which operation that was.
 335
 336    PATH is the canonicalized absolute path at which this node is being
 337    created.
 338
 339    TXN_ID is the Subversion transaction under which this occurs.  */
 340 svn_error_t *svn_fs_base__dag_clone_child(dag_node_t **child_p,
 341                                           dag_node_t *parent,
 342                                           const char *parent_path,
 343                                           const char *name,
 344                                           const char *copy_id,
 345                                           const char *txn_id,
 346                                           trail_t *trail,
 347                                           apr_pool_t *pool);
 348
 349
 350 /* Delete the directory entry named NAME from PARENT, as part of
 351    TRAIL.  PARENT must be mutable.  NAME must be a single path
 352    component; it cannot be a slash-separated directory path.  If the
 353    node being deleted is a mutable directory, remove all mutable nodes
 354    reachable from it.  TXN_ID is the Subversion transaction under
 355    which this occurs.
 356
 357    If return SVN_ERR_FS_NO_SUCH_ENTRY, then there is no entry NAME in
 358    PARENT.  */
 359 svn_error_t *svn_fs_base__dag_delete(dag_node_t *parent,
 360                                      const char *name,
 361                                      const char *txn_id,
 362                                      trail_t *trail,
 363                                      apr_pool_t *pool);
 364
 365
 366 /* Delete the node revision assigned to node ID from FS's `nodes'
 367    table, as part of TRAIL.  Also delete any mutable representations
 368    and strings associated with that node revision.  ID may refer to a
 369    file or directory, which must be mutable.  TXN_ID is the Subversion
 370    transaction under which this occurs.
 371
 372    NOTE: If ID represents a directory, and that directory has mutable
 373    children, you risk orphaning those children by leaving them
 374    dangling, disconnected from all DAG trees.  It is assumed that
 375    callers of this interface know what in the world they are doing.  */
 376 svn_error_t *svn_fs_base__dag_remove_node(svn_fs_t *fs,
 377                                           const svn_fs_id_t *id,
 378                                           const char *txn_id,
 379                                           trail_t *trail,
 380                                           apr_pool_t *pool);
 381
 382
 383 /* Delete all mutable node revisions reachable from node ID, including
 384    ID itself, from FS's `nodes' table, as part of TRAIL.  Also delete
 385    any mutable representations and strings associated with that node
 386    revision.  ID may refer to a file or directory, which may be
 387    mutable or immutable.  TXN_ID is the Subversion transaction under
 388    which this occurs.  */
 389 svn_error_t *svn_fs_base__dag_delete_if_mutable(svn_fs_t *fs,
 390                                                 const svn_fs_id_t *id,
 391                                                 const char *txn_id,
 392                                                 trail_t *trail,
 393                                                 apr_pool_t *pool);
 394
 395
 396 /* Create a new mutable directory named NAME in PARENT, as part of
 397    TRAIL.  Set *CHILD_P to a reference to the new node, allocated in
 398    POOL.  The new directory has no contents, and no properties.
 399    PARENT must be mutable.  NAME must be a single path component; it
 400    cannot be a slash-separated directory path.  PARENT_PATH must be
 401    the canonicalized absolute path of the parent directory.  PARENT
 402    must not currently have an entry named NAME.  Do any temporary
 403    allocation in POOL.  TXN_ID is the Subversion transaction
 404    under which this occurs.  */
 405 svn_error_t *svn_fs_base__dag_make_dir(dag_node_t **child_p,
 406                                        dag_node_t *parent,
 407                                        const char *parent_path,
 408                                        const char *name,
 409                                        const char *txn_id,
 410                                        trail_t *trail,
 411                                        apr_pool_t *pool);
 412
 413
 414 \f
 415 /* Files.  */
 416
 417
 418 /* Set *CONTENTS to a readable generic stream which yields the
 419    contents of FILE, as part of TRAIL.  Allocate the stream in POOL.
 420    If FILE is not a file, return SVN_ERR_FS_NOT_FILE.  */
 421 svn_error_t *svn_fs_base__dag_get_contents(svn_stream_t **contents,
 422                                            dag_node_t *file,
 423                                            trail_t *trail,
 424                                            apr_pool_t *pool);
 425
 426
 427 /* Return a generic writable stream in *CONTENTS with which to set the
 428    contents of FILE as part of TRAIL.  Allocate the stream in POOL.
 429    TXN_ID is the Subversion transaction under which this occurs.  Any
 430    previous edits on the file will be deleted, and a new edit stream
 431    will be constructed.  */
 432 svn_error_t *svn_fs_base__dag_get_edit_stream(svn_stream_t **contents,
 433                                               dag_node_t *file,
 434                                               const char *txn_id,
 435                                               trail_t *trail,
 436                                               apr_pool_t *pool);
 437
 438
 439 /* Signify the completion of edits to FILE made using the stream
 440    returned by svn_fs_base__dag_get_edit_stream, as part of TRAIL.  TXN_ID
 441    is the Subversion transaction under which this occurs.
 442
 443    If CHECKSUM is non-null, it must match the checksum for FILE's
 444    contents (note: this is not recalculated, the recorded checksum is
 445    used), else the error SVN_ERR_CHECKSUM_MISMATCH is returned.
 446
 447    This operation is a no-op if no edits are present.  */
 448 svn_error_t *svn_fs_base__dag_finalize_edits(dag_node_t *file,
 449                                              const char *checksum,
 450                                              const char *txn_id,
 451                                              trail_t *trail,
 452                                              apr_pool_t *pool);
 453
 454
 455 /* Set *LENGTH to the length of the contents of FILE, as part of TRAIL. */
 456 svn_error_t *svn_fs_base__dag_file_length(svn_filesize_t *length,
 457                                           dag_node_t *file,
 458                                           trail_t *trail,
 459                                           apr_pool_t *pool);
 460
 461 /* Put the recorded MD5 checksum of FILE into DIGEST, as part of
 462  * TRAIL.  DIGEST must point to APR_MD5_DIGESTSIZE bytes of storage.
 463  *
 464  * If no stored checksum is available, do not calculate the checksum,
 465  * just put all 0's into DIGEST.
 466  */
 467 svn_error_t *
 468 svn_fs_base__dag_file_checksum(unsigned char digest[],
 469                                dag_node_t *file,
 470                                trail_t *trail,
 471                                apr_pool_t *pool);
 472
 473 /* Create a new mutable file named NAME in PARENT, as part of TRAIL.
 474    Set *CHILD_P to a reference to the new node, allocated in
 475    POOL.  The new file's contents are the empty string, and it
 476    has no properties.  PARENT must be mutable.  NAME must be a single
 477    path component; it cannot be a slash-separated directory path.
 478    PARENT_PATH must be the canonicalized absolute path of the parent
 479    directory.  TXN_ID is the Subversion transaction under which this
 480    occurs.  */
 481 svn_error_t *svn_fs_base__dag_make_file(dag_node_t **child_p,
 482                                         dag_node_t *parent,
 483                                         const char *parent_path,
 484                                         const char *name,
 485                                         const char *txn_id,
 486                                         trail_t *trail,
 487                                         apr_pool_t *pool);
 488
 489
 490 \f
 491 /* Copies */
 492
 493 /* Make ENTRY in TO_NODE be a copy of FROM_NODE, as part of TRAIL.
 494    TO_NODE must be mutable.  TXN_ID is the Subversion transaction
 495    under which this occurs.
 496
 497    If PRESERVE_HISTORY is true, the new node will record that it was
 498    copied from FROM_PATH in FROM_REV; therefore, FROM_NODE should be
 499    the node found at FROM_PATH in FROM_REV, although this is not
 500    checked.
 501
 502    If PRESERVE_HISTORY is false, FROM_PATH and FROM_REV are ignored.  */
 503 svn_error_t *svn_fs_base__dag_copy(dag_node_t *to_node,
 504                                    const char *entry,
 505                                    dag_node_t *from_node,
 506                                    svn_boolean_t preserve_history,
 507                                    svn_revnum_t from_rev,
 508                                    const char *from_path,
 509                                    const char *txn_id,
 510                                    trail_t *trail,
 511                                    apr_pool_t *pool);
 512
 513
 514 \f
 515 /* Deltification */
 516
 517 /* Change TARGET's representation to be a delta against SOURCE, as
 518    part of TRAIL.  If TARGET or SOURCE does not exist, do nothing and
 519    return success.  If PROPS_ONLY is non-zero, only the node property
 520    portion of TARGET will be deltified.
 521
 522    WARNING WARNING WARNING: Do *NOT* call this with a mutable SOURCE
 523    node.  Things will go *very* sour if you deltify TARGET against a
 524    node that might just disappear from the filesystem in the (near)
 525    future.  */
 526 svn_error_t *svn_fs_base__dag_deltify(dag_node_t *target,
 527                                       dag_node_t *source,
 528                                       svn_boolean_t props_only,
 529                                       trail_t *trail,
 530                                       apr_pool_t *pool);
 531
 532 \f
 533 /* Comparison */
 534
 535 /* Find out what is the same between two nodes.
 536
 537    If PROPS_CHANGED is non-null, set *PROPS_CHANGED to 1 if the two
 538    nodes have different property lists, or to 0 if same.
 539
 540    If CONTENTS_CHANGED is non-null, set *CONTENTS_CHANGED to 1 if the
 541    two nodes have different contents, or to 0 if same.  For files,
 542    file contents are compared; for directories, the entries lists are
 543    compared.  If one is a file and the other is a directory, the one's
 544    contents will be compared to the other's entries list.  (Not
 545    terribly useful, I suppose, but that's the caller's business.)
 546
 547    ### todo: This function only compares rep keys at the moment.  This
 548    may leave us with a slight chance of a false positive, though I
 549    don't really see how that would happen in practice.  Nevertheless,
 550    it should probably be fixed.  */
 551 svn_error_t *svn_fs_base__things_different(svn_boolean_t *props_changed,
 552                                            svn_boolean_t *contents_changed,
 553                                            dag_node_t *node1,
 554                                            dag_node_t *node2,
 555                                            trail_t *trail,
 556                                            apr_pool_t *pool);
 557
 558
 559 #ifdef __cplusplus
 560 }
 561 #endif /* __cplusplus */
 562
 563 #endif /* SVN_LIBSVN_FS_DAG_H */