filesystem transactions

Filesystem Transactions. More...

Modules

 Bitmask flags for svn_fs_begin_txn2()

Typedefs

typedef svn_fs_txn_t svn_fs_txn_t
 The type of a Subversion transaction object.

Functions

svn_error_tsvn_fs_begin_txn2 (svn_fs_txn_t **txn_p, svn_fs_t *fs, svn_revnum_t rev, apr_uint32_t flags, apr_pool_t *pool)
 Begin a new transaction on the filesystem fs, based on existing revision rev.
svn_error_tsvn_fs_begin_txn (svn_fs_txn_t **txn_p, svn_fs_t *fs, svn_revnum_t rev, apr_pool_t *pool)
 Same as svn_fs_begin_txn2(), but with flags set to 0.
svn_error_tsvn_fs_commit_txn (const char **conflict_p, svn_revnum_t *new_rev, svn_fs_txn_t *txn, apr_pool_t *pool)
 Commit txn.
svn_error_tsvn_fs_abort_txn (svn_fs_txn_t *txn, apr_pool_t *pool)
 Abort the transaction txn.
svn_error_tsvn_fs_purge_txn (svn_fs_t *fs, const char *txn_id, apr_pool_t *pool)
 Cleanup the dead transaction in fs whose ID is txn_id.
svn_error_tsvn_fs_txn_name (const char **name_p, svn_fs_txn_t *txn, apr_pool_t *pool)
 Set *name_p to the name of the transaction txn, as a null-terminated string.
svn_revnum_t svn_fs_txn_base_revision (svn_fs_txn_t *txn)
 Return txn's base revision.
svn_error_tsvn_fs_open_txn (svn_fs_txn_t **txn, svn_fs_t *fs, const char *name, apr_pool_t *pool)
 Open the transaction named name in the filesystem fs.
svn_error_tsvn_fs_list_transactions (apr_array_header_t **names_p, svn_fs_t *fs, apr_pool_t *pool)
 Set *names_p to an array of const char * ids which are the names of all the currently active transactions in the filesystem fs.
svn_error_tsvn_fs_txn_prop (svn_string_t **value_p, svn_fs_txn_t *txn, const char *propname, apr_pool_t *pool)
 Set *value_p to the value of the property named propname on transaction txn.
svn_error_tsvn_fs_txn_proplist (apr_hash_t **table_p, svn_fs_txn_t *txn, apr_pool_t *pool)
 Set *table_p to the entire property list of transaction txn in filesystem fs, as an APR hash table allocated in pool.
svn_error_tsvn_fs_change_txn_prop (svn_fs_txn_t *txn, const char *name, const svn_string_t *value, apr_pool_t *pool)
 Change a transactions txn's property's value, or add/delete a property.

Detailed Description

Filesystem Transactions.

To make a change to a Subversion filesystem:

The filesystem implementation guarantees that your commit will either:

Until you commit the transaction, any changes you make are invisible. Only when your commit succeeds do they become visible to the outside world, as a new revision of the filesystem.

If you begin a transaction, and then decide you don't want to make the change after all (say, because your net connection with the client disappeared before the change was complete), you can call svn_fs_abort_txn(), to cancel the entire transaction; this leaves the filesystem unchanged.

The only way to change the contents of files or directories, or their properties, is by making a transaction and creating a new revision, as described above. Once a revision has been committed, it never changes again; the filesystem interface provides no means to go back and edit the contents of an old revision. Once history has been recorded, it is set in stone. Clients depend on this property to do updates and commits reliably; proxies depend on this property to cache changes accurately; and so on.

There are two kinds of nodes in the filesystem: mutable, and immutable. Revisions in the filesystem consist entirely of immutable nodes, whose contents never change. A transaction in progress, which the user is still constructing, uses mutable nodes for those nodes which have been changed so far, and refers to immutable nodes from existing revisions for portions of the tree which haven't been changed yet in that transaction.

Immutable nodes, as part of revisions, never refer to mutable nodes, which are part of uncommitted transactions. Mutable nodes may refer to immutable nodes, or other mutable nodes.

Note that the terms "immutable" and "mutable" describe whether or not the nodes have been changed as part of a transaction --- not the permissions on the nodes they refer to. Even if you aren't authorized to modify the filesystem's root directory, you might be authorized to change some descendant of the root; doing so would create a new mutable copy of the root directory. Mutability refers to the role of the node: part of an existing revision, or part of a new one. This is independent of your authorization to make changes to a given node.

Transactions are actually persistent objects, stored in the database. You can open a filesystem, begin a transaction, and close the filesystem, and then a separate process could open the filesystem, pick up the same transaction, and continue work on it. When a transaction is successfully committed, it is removed from the database.

Every transaction is assigned a name. You can open a transaction by name, and resume work on it, or find out the name of a transaction you already have open. You can also list all the transactions currently present in the database.

Transaction names are guaranteed to contain only letters (upper- and lower-case), digits, `-', and `.', from the ASCII character set.


Function Documentation

svn_error_t* svn_fs_abort_txn svn_fs_txn_t txn,
apr_pool_t *  pool
 

Abort the transaction txn.

Any changes made in txn are discarded, and the filesystem is left unchanged. Use pool for any necessary allocations.

Note:
This function first sets the state of txn to "dead", and then attempts to purge it and any related data from the filesystem. If some part of the cleanup process fails, txn and some portion of its data may remain in the database after this function returns. Use svn_fs_purge_txn() to retry the transaction cleanup.

svn_error_t* svn_fs_begin_txn svn_fs_txn_t **  txn_p,
svn_fs_t fs,
svn_revnum_t  rev,
apr_pool_t *  pool
 

Same as svn_fs_begin_txn2(), but with flags set to 0.

Deprecated:
Provided for backward compatibility with the 1.1 API.

svn_error_t* svn_fs_begin_txn2 svn_fs_txn_t **  txn_p,
svn_fs_t fs,
svn_revnum_t  rev,
apr_uint32_t  flags,
apr_pool_t *  pool
 

Begin a new transaction on the filesystem fs, based on existing revision rev.

Set *txn_p to a pointer to the new transaction. When committed, this transaction will create a new revision.

Allocate the new transaction in pool; when pool is freed, the new transaction will be closed (neither committed nor aborted).

flags determines transaction enforcement behaviors, and is composed from the constants SVN_FS_TXN_* (SVN_FS_TXN_CHECK_OOD etc.).

Note:
If you're building a txn for committing, you probably don't want to call this directly. Instead, call svn_repos_fs_begin_txn_for_commit(), which honors the repository's hook configurations.
Since:
New in 1.2.

svn_error_t* svn_fs_change_txn_prop svn_fs_txn_t txn,
const char *  name,
const svn_string_t value,
apr_pool_t *  pool
 

Change a transactions txn's property's value, or add/delete a property.

name is the name of the property to change, and value is the new value of the property, or zero if the property should be removed altogether. Do any necessary temporary allocation in pool.

svn_error_t* svn_fs_commit_txn const char **  conflict_p,
svn_revnum_t new_rev,
svn_fs_txn_t txn,
apr_pool_t *  pool
 

Commit txn.

Note:
You usually don't want to call this directly. Instead, call svn_repos_fs_commit_txn(), which honors the repository's hook configurations.
If the transaction conflicts with other changes committed to the repository, return an SVN_ERR_FS_CONFLICT error. Otherwise, create a new filesystem revision containing the changes made in txn, storing that new revision number in *new_rev, and return zero.

If conflict_p is non-zero, use it to provide details on any conflicts encountered merging txn with the most recent committed revisions. If a conflict occurs, set *conflict_p to the path of the conflict in txn, with the same lifetime as txn; otherwise, set *conflict_p to null.

If the commit succeeds, txn is invalid.

If the commit fails, txn is still valid; you can make more operations to resolve the conflict, or call svn_fs_abort_txn() to abort the transaction.

Note:
Success or failure of the commit of txn is determined by examining the value of *new_rev upon this function's return. If the value is a valid revision number, the commit was successful, even though a non-NULL function return value may indicate that something else went wrong.

svn_error_t* svn_fs_list_transactions apr_array_header_t **  names_p,
svn_fs_t fs,
apr_pool_t *  pool
 

Set *names_p to an array of const char * ids which are the names of all the currently active transactions in the filesystem fs.

Allocate the array in pool.

svn_error_t* svn_fs_open_txn svn_fs_txn_t **  txn,
svn_fs_t fs,
const char *  name,
apr_pool_t *  pool
 

Open the transaction named name in the filesystem fs.

Set *txn to the transaction.

If there is no such transaction, SVN_ERR_FS_NO_SUCH_TRANSACTION is the error returned.

Allocate the new transaction in pool; when pool is freed, the new transaction will be closed (neither committed nor aborted).

svn_error_t* svn_fs_purge_txn svn_fs_t fs,
const char *  txn_id,
apr_pool_t *  pool
 

Cleanup the dead transaction in fs whose ID is txn_id.

Use pool for all allocations. If the transaction is not yet dead, the error SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned. (The caller probably forgot to abort the transaction, or the cleanup step of that abort failed for some reason.)

svn_error_t* svn_fs_txn_name const char **  name_p,
svn_fs_txn_t txn,
apr_pool_t *  pool
 

Set *name_p to the name of the transaction txn, as a null-terminated string.

Allocate the name in pool.

svn_error_t* svn_fs_txn_prop svn_string_t **  value_p,
svn_fs_txn_t txn,
const char *  propname,
apr_pool_t *  pool
 

Set *value_p to the value of the property named propname on transaction txn.

If txn has no property by that name, set *value_p to zero. Allocate the result in pool.

svn_error_t* svn_fs_txn_proplist apr_hash_t **  table_p,
svn_fs_txn_t txn,
apr_pool_t *  pool
 

Set *table_p to the entire property list of transaction txn in filesystem fs, as an APR hash table allocated in pool.

The resulting table maps property names to pointers to svn_string_t objects containing the property value.


Generated on Wed Mar 23 12:11:32 2011 for Subversion by  doxygen 1.4.6