svn commit: r1102894 - /subversion/trunk/subversion/include/svn_delta.h

[cm...@apache.org]

Author: cmpilato
Date: Fri May 13 20:45:27 2011
New Revision: 1102894

URL: http://svn.apache.org/viewvc?rev=1102894&view=rev
Log:
Add suggestions about editor implementation pool usage.

* subversion/include/svn_delta.h
  (svn_delta_editor_t): Add a note about pool usage with respect to
    the postfix deltas paradigm on the 'add_file' and 'open_file'
    editor functions.

Modified:
    subversion/trunk/subversion/include/svn_delta.h

Modified: subversion/trunk/subversion/include/svn_delta.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_delta.h?rev=1102894&r1=1102893&r2=1102894&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_delta.h (original)
+++ subversion/trunk/subversion/include/svn_delta.h Fri May 13 20:45:27 2011
@@ -927,6 +927,16 @@ typedef struct svn_delta_editor_t
    * Allocations for the returned @a file_baton should be performed in
    * @a file_pool. It is also typical to save this pool for later usage
    * by @c apply_textdelta and possibly @c close_file.
+   *
+   * @note Because the editor driver could be employing the "postfix
+   * deltas" paradigm, @a file_pool could potentially be relatively
+   * long-lived.  Every file baton created by the editor for a given
+   * editor drive might be resident in memory similtaneously.  Editor
+   * implementations should ideally keep their file batons as
+   * conservative (memory-usage-wise) as possible, and use @a file_pool
+   * only for those batons.  (Consider using a subpool of @a file_pool
+   * for scratch work, destroying the subpool before exiting this
+   * function's implementation.)
    */
   svn_error_t *(*add_file)(const char *path,
                            void *parent_baton,
@@ -946,6 +956,9 @@ typedef struct svn_delta_editor_t
    * Allocations for the returned @a file_baton should be performed in
    * @a file_pool. It is also typical to save this pool for later usage
    * by @c apply_textdelta and possibly @c close_file.
+   *
+   * @note See note about memory usage on @a add_file, which also
+   * applies here.
    */
   svn_error_t *(*open_file)(const char *path,
                             void *parent_baton,