Mailing-List: contact commits-help@subversion.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@subversion.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1332062 - in /subversion/trunk: notes/api-errata/1.8/
 notes/api-errata/1.8/fs001.txt subversion/include/svn_fs.h
Date: Mon, 30 Apr 2012 06:13:36 -0000
To: commits@subversion.apache.org
From: gstein@apache.org
Message-Id: <20120430061336.76825238890B@eris.apache.org>

Author: gstein
Date: Mon Apr 30 06:13:35 2012
New Revision: 1332062

URL: http://svn.apache.org/viewvc?rev=1332062&view=rev
Log:
Fix the docstring for svn_fs_commit_txn().

Approach reviewed by: danielsh

* subversion/include/svn_fs.h:
  (svn_fs_commit_txn): fix docstring to note where CONFLICT_PATH is
    actually allocated.

* notes/api-errata/1.8: new directory

* notes/api-errata/1.8/fs001.txt: we are nominally changing the
    semantics of svn_fs_commit_txn, or at least the possible
    expectation that callers have. they should review their usage.

Added:
    subversion/trunk/notes/api-errata/1.8/
    subversion/trunk/notes/api-errata/1.8/fs001.txt
Modified:
    subversion/trunk/subversion/include/svn_fs.h

Added: subversion/trunk/notes/api-errata/1.8/fs001.txt
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/api-errata/1.8/fs001.txt?rev=1332062&view=auto
==============================================================================
--- subversion/trunk/notes/api-errata/1.8/fs001.txt (added)
+++ subversion/trunk/notes/api-errata/1.8/fs001.txt Mon Apr 30 06:13:35 2012
@@ -0,0 +1,35 @@
+API ERRATE -- $Id$
+
+Root Cause of Errata: implementation/docstring mismatch
+ Library(s) Affected: libsvn_fs_fs, libsvn_fs_base, libsvn_repos
+Function(s) Affected: svn_fs_commit_txn, svn_repos_fs_commit_txn
+     New Behavior in: n/a
+      Related Issues: n/a
+
+
+== Details ==
+
+The docstring for svn_fs_commit_txn() stated that the returned
+CONFLICT_PATH value was allocated in the transaction's pool. However,
+the two implementations (BDB and FSFS) allocate the path in the POOL
+parameter passed to the function.
+
+This behavior is directly propagated to the svn_repos_fs_commit_txn
+function and its CONFLICT_PATH and POOL parameters.
+
+For the 1.8 release, the docstring has been updated to match the
+implementation: the path is allocated in the provided pool.
+
+
+== Impact on API Users ==
+
+If an API user expected the path to live in the transaction pool, then
+it may run into problems depending upon the lifetime of the provided
+pool, relative to the transaction pool. A number of callers abort the
+transaction when such a conflict occurs; if the implementation had
+actually placed the path into the transaction pool, it would become
+invalid when the transaction is aborted and likely cause problems for
+any caller truly expecting the path to live in the transaction pool.
+
+All API users should review their use of the CONFLICT_PATH parameter
+and the necessary lifetime.

Modified: subversion/trunk/subversion/include/svn_fs.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_fs.h?rev=1332062&r1=1332061&r2=1332062&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_fs.h (original)
+++ subversion/trunk/subversion/include/svn_fs.h Mon Apr 30 06:13:35 2012
@@ -865,7 +865,7 @@ svn_fs_begin_txn(svn_fs_txn_t **txn_p,
  * If @a conflict_p is non-zero, use it to provide details on any
  * conflicts encountered merging @a txn with the most recent committed
  * revisions.  If a conflict occurs, set @a *conflict_p to the path of
- * the conflict in @a txn, with the same lifetime as @a txn;
+ * the conflict in @a txn, allocated within @a pool;
  * otherwise, set @a *conflict_p to NULL.
  *
  * If the commit succeeds, @a txn is invalid.