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