dag.h

linux subdivision ying gai ke yi le ba

/* dag.h : DAG-like interface filesystem, private to libsvn_fs
 *
 * ====================================================================
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 */

#ifndef SVN_LIBSVN_FS_DAG_H
#define SVN_LIBSVN_FS_DAG_H

#include "svn_fs.h"

#include "trail.h"

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


/* The interface in this file provides all the essential filesystem
   operations, but exposes the filesystem's DAG structure.  This makes
   it simpler to implement than the public interface, since a client
   of this interface has to understand and cope with shared structure
   directly as it appears in the database.  However, it's still a
   self-consistent set of invariants to maintain, making it
   (hopefully) a useful interface boundary.

   In other words:

   - The dag_node_t interface exposes the internal DAG structure of
     the filesystem, while the svn_fs.h interface does any cloning
     necessary to make the filesystem look like a tree.

   - The dag_node_t interface exposes the existence of copy nodes,
     whereas the svn_fs.h handles them transparently.

   - dag_node_t's must be explicitly cloned, whereas the svn_fs.h
     operations make clones implicitly.

   - Callers of the dag_node_t interface use Berkeley DB transactions
     to ensure consistency between operations, while callers of the
     svn_fs.h interface use Subversion transactions.  */


/* Initializing a filesystem.  */


/* Given a filesystem FS, which contains all the necessary tables,
   create the initial revision 0, and the initial root directory.  */
svn_error_t *svn_fs_base__dag_init_fs (svn_fs_t *fs);



/* Generic DAG node stuff.  */

typedef struct dag_node_t dag_node_t;


/* Fill *NODE with a dag_node_t representing node revision ID in FS,
   allocating in TRAIL->pool.  */
svn_error_t *
svn_fs_base__dag_get_node (dag_node_t **node,
                           svn_fs_t *fs,
                           const svn_fs_id_t *id,
                           trail_t *trail);


/* Return a new dag_node_t object referring to the same node as NODE,
   allocated in POOL.  If you're trying to build a structure in a
   trail that wants to refer to dag nodes that may have been allocated
   elsewhere, you can call this function, passing "trail->pool", and
   avoid inter-pool pointers.  */
dag_node_t *svn_fs_base__dag_dup (dag_node_t *node,
                                  apr_pool_t *pool);


/* Return the filesystem containing NODE.  */
svn_fs_t *svn_fs_base__dag_get_fs (dag_node_t *node);


/* Set *REV to NODE's revision number, as part of TRAIL.  If NODE has
   never been committed as part of a revision, set *REV to
   SVN_INVALID_REVNUM.  */
svn_error_t *svn_fs_base__dag_get_revision (svn_revnum_t *rev,
                                            dag_node_t *node,
                                            trail_t *trail);


/* Return the node revision ID of NODE.  The value returned is shared
   with NODE, and will be deallocated when NODE is.  */
const svn_fs_id_t *svn_fs_base__dag_get_id (dag_node_t *node);


/* Return the created path of NODE.  The value returned is shared
   with NODE, and will be deallocated when NODE is.  */
const char *svn_fs_base__dag_get_created_path (dag_node_t *node);


/* Set *ID_P to the node revision ID of NODE's immediate predecessor,
   or NULL if NODE has no predecessor, as part of TRAIL.  The returned
   ID will be allocated in TRAIL->pool.  */
svn_error_t *svn_fs_base__dag_get_predecessor_id (const svn_fs_id_t **id_p,
                                                  dag_node_t *node,
                                                  trail_t *trail);


/* Set *COUNT to the number of predecessors NODE has (recursively), or
   -1 if not known, as part of TRAIL.  */
svn_error_t *svn_fs_base__dag_get_predecessor_count (int *count,
                                                     dag_node_t *node,
                                                     trail_t *trail);


/* Callback function type for svn_fs_base__dag_walk_predecessors() */
typedef svn_error_t *(*dag_pred_func_t) (void *baton,
                                         dag_node_t *node,
                                         svn_boolean_t *done,
                                         trail_t *trail);

/* Walk over NODE's predecessor list, calling CALLBACK (with its
   associated BATON) for each predecessor until the callback returns
   an error (in which case, return that error) or until it sets its
   DONE flag.  When the predecessor walk reaches a node with no
   predecessor, it will call the CALLBACK one final time with a NULL
   `node' argument to indicate that the predecessor walk is now
   complete.

   Do all this as part of TRAIL.  */
svn_error_t *svn_fs_base__dag_walk_predecessors (dag_node_t *node,
                                                 dag_pred_func_t callback,
                                                 void *baton,
                                                 trail_t *trail);

/* Return non-zero IFF NODE is currently mutable under Subversion
   transaction TXN_ID.  */
svn_boolean_t svn_fs_base__dag_check_mutable (dag_node_t *node,
                                              const char *txn_id);

/* Return the node kind of NODE. */
svn_node_kind_t svn_fs_base__dag_node_kind (dag_node_t *node);

/* Set *PROPLIST_P to a PROPLIST hash representing the entire property
   list of NODE, as part of TRAIL.  The hash has const char * names
   (the property names) and svn_string_t * values (the property values).

   If properties do not exist on NODE, *PROPLIST_P will be set to NULL.

   The returned property list is allocated in TRAIL->pool.  */
svn_error_t *svn_fs_base__dag_get_proplist (apr_hash_t **proplist_p,
                                            dag_node_t *node,
                                            trail_t *trail);

/* Set the property list of NODE to PROPLIST, as part of TRAIL.  The
   node being changed must be mutable.  TXN_ID is the Subversion
   transaction under which this occurs.  */
svn_error_t *svn_fs_base__dag_set_proplist (dag_node_t *node,
                                            apr_hash_t *proplist,
                                            const char *txn_id,
                                            trail_t *trail);



/* Revision and transaction roots.  */


/* Open the root of revision REV of filesystem FS, as part of TRAIL.
   Set *NODE_P to the new node.  Allocate the node in TRAIL->pool.  */
svn_error_t *svn_fs_base__dag_revision_root (dag_node_t **node_p,
                                             svn_fs_t *fs,
                                             svn_revnum_t rev,
                                             trail_t *trail);


/* Set *NODE_P to the root of transaction TXN_ID in FS, as part
   of TRAIL.  Allocate the node in TRAIL->pool.

   Note that the root node of TXN_ID is not necessarily mutable.  If no
   changes have been made in the transaction, then it may share its
   root directory with its base revision.  To get a mutable root node
   for a transaction, call svn_fs_base__dag_clone_root.  */
svn_error_t *svn_fs_base__dag_txn_root (dag_node_t **node_p,
                                        svn_fs_t *fs,
                                        const char *txn_id,
                                        trail_t *trail);


/* Set *NODE_P to the base root of transaction TXN_ID in FS, as part
   of TRAIL.  Allocate the node in TRAIL->pool.  */
svn_error_t *svn_fs_base__dag_txn_base_root (dag_node_t **node_p,
                                             svn_fs_t *fs,
                                             const char *txn_id,
                                             trail_t *trail);


/* Clone the root directory of TXN_ID in FS, and update the
   `transactions' table entry to point to it, unless this has been
   done already.  In either case, set *ROOT_P to a reference to the
   root directory clone.  Do all this as part of TRAIL, and allocate
   *ROOT_P in TRAIL->pool.  */
svn_error_t *svn_fs_base__dag_clone_root (dag_node_t **root_p,
                                          svn_fs_t *fs,
                                          const char *txn_id,
                                          trail_t *trail);


/* Commit the transaction TXN_ID in FS, as part of TRAIL.  Store the
   new revision number in *NEW_REV.  This entails:
   - marking the tree of mutable nodes at TXN_ID's root as immutable,
     and marking all their contents as stable
   - creating a new revision, with TXN_ID's root as its root directory
   - promoting TXN_ID to a "committed" transaction.

   Beware!  This does not make sure that TXN_ID is based on the very
   latest revision in FS.  If the caller doesn't take care of this,
   you may lose people's work!

   Do any necessary temporary allocation in a subpool of TRAIL->pool.
   Consume temporary space at most proportional to the maximum depth
   of SVN_TXN's tree of mutable nodes.  */
svn_error_t *svn_fs_base__dag_commit_txn (svn_revnum_t *new_rev,
                                          svn_fs_t *fs,
                                          const char *txn_id,
                                          trail_t *trail);



/* Directories.  */


/* Open the node named NAME in the directory PARENT, as part of TRAIL.
   Set *CHILD_P to the new node, allocated in TRAIL->pool.  NAME must be a
   single path component; it cannot be a slash-separated directory
   path.  */
svn_error_t *svn_fs_base__dag_open (dag_node_t **child_p,
                                    dag_node_t *parent,
                                    const char *name,
                                    trail_t *trail);


/* Set *ENTRIES_P to a hash table of NODE's entries, as part of TRAIL,
   or NULL if NODE has no entries.  The keys of the table are entry
   names, and the values are svn_fs_dirent_t's.

   The returned table is allocated in *either* TRAIL->pool or the pool
   NODE was allocated in, at this function's discretion; the caller
   must finish using it while both of those remain live.  If the
   caller needs the table to live longer, it should copy the hash.

   NOTE: the 'kind' field of the svn_fs_dirent_t's is set to
   svn_node_unknown by this function -- callers that need in
   interesting value in these slots should fill them in using a new
   TRAIL, since the list of entries can be arbitrarily large.  */
svn_error_t *svn_fs_base__dag_dir_entries (apr_hash_t **entries_p,
                                           dag_node_t *node,