Filesystem Transactions. More...

Modules
	Bitmask flags for svn_fs_begin_txn2()

Typedefs
typedef struct svn_fs_txn_t	svn_fs_txn_t
	The type of a Subversion transaction object. More...

Functions
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. More...

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. More...

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. More...

svn_error_t *	svn_fs_abort_txn (svn_fs_txn_t txn, apr_pool_t pool)
	Abort the transaction txn. More...

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. More...

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. More...

svn_revnum_t	svn_fs_txn_base_revision (svn_fs_txn_t *txn)
	Return txn's base revision. More...

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. More...

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. More...

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. More...

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, as an APR hash table allocated in pool*. More...

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. More...

svn_error_t *	svn_fs_change_txn_props (svn_fs_txn_t txn, const apr_array_header_t props, apr_pool_t *pool)
	Change, add, and/or delete transaction property values in transaction txn. More...

Detailed Description

Filesystem Transactions.

To make a change to a Subversion filesystem:

Create a transaction object, using svn_fs_begin_txn().
Call svn_fs_txn_root(), to get the transaction's root directory.
Make whatever changes you like in that tree.
Commit the transaction, using svn_fs_commit_txn().

The filesystem implementation guarantees that your commit will either:

succeed completely, so that all of the changes are committed to create a new revision of the filesystem, or
fail completely, leaving the filesystem unchanged.

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.

You may assign properties to transactions; these are name/value pairs. When you commit a transaction, all of its properties become unversioned revision properties of the new revision. (There is one exception: the svn:date property will be automatically set on new transactions to the date that the transaction was created, and will be overwritten when the transaction is committed by the current time; changes to a transaction's svn:date property will not affect its committed value.)

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

The Subversion filesystem will make a best effort to not reuse transaction names. The Berkeley DB backend generates transaction names using a sequence, or a counter, which is stored in the BDB database. Each new transaction increments the counter. The current value of the counter is not serialized into a filesystem dump file, so dumping and restoring the repository will reset the sequence and reuse transaction names. The FSFS backend generates a transaction name using the hostname, process ID and current time in microseconds since 00:00:00 January 1, 1970 UTC. So it is extremely unlikely that a transaction name will be reused.

Typedef Documentation

typedef struct svn_fs_txn_t svn_fs_txn_t

The type of a Subversion transaction object.

Definition at line 855 of file svn_fs.h.

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_change_txn_props	(	svn_fs_txn_t *	txn,
		const apr_array_header_t *	props,
		apr_pool_t *	pool
	)

Change, add, and/or delete transaction property values in transaction txn.

props is an array of svn_prop_t elements. This is equivalent to calling svn_fs_change_txn_prop() multiple times with the name and value fields of each successive svn_prop_t, but may be more efficient. (Properties not mentioned are left alone.) Do any necessary temporary allocation in pool.

Since: New in 1.5.

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, allocated within pool; otherwise, set *conflict_p to NULL.

If the commit succeeds, txn is invalid.

If the commit fails for any reason, *new_rev is an invalid revision number, an error other than SVN_NO_ERROR is returned and 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 in post commit FS processing.; See api-errata/1.8/fs001.txt for information on how this function was documented in versions prior to 1.8.

need to document this better. there are four combinations of

return values:

1) err=NULL. conflict=NULL. new_rev is valid

2) err=SVN_ERR_FS_CONFLICT. conflict is set. new_rev=SVN_INVALID_REVNUM

3) err=!NULL. conflict=NULL. new_rev is valid

4) err=!NULL. conflict=NULL. new_rev=SVN_INVALID_REVNUM

some invariants:

*conflict_p will be non-NULL IFF SVN_ERR_FS_CONFLICT

if *conflict_p is set (and SVN_ERR_FS_CONFLICT), then new_rev

will always be SVN_INVALID_REVNUM

*conflict_p will always be initialized to NULL, or to a valid

conflict string

*new_rev will always be initialized to SVN_INVALID_REVNUM, or

to a valid, committed revision number

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_revnum_t svn_fs_txn_base_revision ( svn_fs_txn_t * txn )

Return txn's base revision.

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, 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.

Modules

Typedefs

Functions