svn commit: r1710201 - in /subversion/trunk/subversion: include/svn_io.h libsvn_subr/stream.c

[ju...@apache.org]

Author: julianfoad
Date: Fri Oct 23 12:49:45 2015
New Revision: 1710201

URL: http://svn.apache.org/viewvc?rev=1710201&view=rev
Log:
Improve the documentation of svn_stringbuf[buf]_from_stream(), especially in
describing the length hint parameter and in documenting the two similar
functions the same way.

Also rename the output parameter of one of them for consistency with the
other.

* subversion/include/svn_io.h
  (svn_stringbuf_from_stream): Rename the output parameter 'str' to 'result'.
    Improve the documentation.
  (svn_string_from_stream2): Improve the documentation.

* subversion/libsvn_subr/stream.c
  (svn_stringbuf_from_stream): Rename the output parameter 'str' to 'result'.
    Document the performance characteristics.

Modified:
    subversion/trunk/subversion/include/svn_io.h
    subversion/trunk/subversion/libsvn_subr/stream.c

Modified: subversion/trunk/subversion/include/svn_io.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_io.h?rev=1710201&r1=1710200&r2=1710201&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_io.h (original)
+++ subversion/trunk/subversion/include/svn_io.h Fri Oct 23 12:49:45 2015
@@ -1147,16 +1147,27 @@ svn_error_t *
 svn_stream_for_stdout(svn_stream_t **out,
                       apr_pool_t *pool);
 
-/** Set @a *str to a string buffer allocated in @a result_pool that contains
- * all data from the current position in @a stream to its end.  @a len_hint
- * specifies the initial capacity of the string buffer and may be 0.  The
- * buffer gets automatically resized to fit the actual amount of data being
- * read from @a stream.
+/** Read the contents of @a stream into memory, from its current position
+ * to its end, returning the data in @a *result. The stream will be closed
+ * when it has been successfully and completely read.
+ *
+ * @a len_hint gives a hint about the expected length, in bytes, of the
+ * actual data that will be read from the stream. It may be 0, meaning no
+ * hint is being provided. Efficiency in time and/or in space may be
+ * better (and in general will not be worse) when the actual data length
+ * is equal or approximately equal to the length hint.
+ *
+ * The returned memory is allocated in @a result_pool.
+ *
+ * @note The present implementation is efficient when @a len_hint is big
+ * enough (but not vastly bigger than necessary), and also for actual
+ * lengths up to 64 bytes when @a len_hint is 0. Otherwise it can incur
+ * significant time and space overheads. See source code for details.
  *
  * @since New in 1.9.
  */
 svn_error_t *
-svn_stringbuf_from_stream(svn_stringbuf_t **str,
+svn_stringbuf_from_stream(svn_stringbuf_t **result,
                           svn_stream_t *stream,
                           apr_size_t len_hint,
                           apr_pool_t *result_pool);
@@ -1520,18 +1531,23 @@ svn_stream_contents_same(svn_boolean_t *
                          apr_pool_t *pool);
 
 
-/** Read the contents of @a stream into memory, returning the data in
- * @a result. The stream will be closed when it has been successfully and
- * completely read.
- *
- * @a len_hint specifies the initial capacity of the string buffer and
- * may be 0.
+/** Read the contents of @a stream into memory, from its current position
+ * to its end, returning the data in @a *result. The stream will be closed
+ * when it has been successfully and completely read.
+ *
+ * @a len_hint gives a hint about the expected length, in bytes, of the
+ * actual data that will be read from the stream. It may be 0, meaning no
+ * hint is being provided. Efficiency in time and/or in space may be
+ * better (and in general will not be worse) when the actual data length
+ * is equal or approximately equal to the length hint.
  *
  * The returned memory is allocated in @a result_pool, and any temporary
- * allocations are performed in @a scratch_pool.
+ * allocations may be performed in @a scratch_pool.
  *
- * @note due to memory pseudo-reallocation behavior (due to pools), this
- *   can be a memory-intensive operation for large files.
+ * @note The present implementation is efficient when @a len_hint is big
+ * enough (but not vastly bigger than necessary), and also for actual
+ * lengths up to 64 bytes when @a len_hint is 0. Otherwise it can incur
+ * significant time and space overheads. See source code for details.
  *
  * @since New in 1.10
  */

Modified: subversion/trunk/subversion/libsvn_subr/stream.c
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/libsvn_subr/stream.c?rev=1710201&r1=1710200&r2=1710201&view=diff
==============================================================================
--- subversion/trunk/subversion/libsvn_subr/stream.c (original)
+++ subversion/trunk/subversion/libsvn_subr/stream.c Fri Oct 23 12:49:45 2015
@@ -1481,8 +1481,18 @@ svn_stream_checksummed2(svn_stream_t *st
 
 /* Miscellaneous stream functions. */
 
+/*
+ * [JAF] By considering the buffer size doubling algorithm we use, I think
+ * the performance characteristics of this implementation are as follows:
+ *
+ * When the effective hint is big enough for the actual data, it uses
+ * minimal time and allocates space roughly equal to the effective hint.
+ * Otherwise, it incurs a time overhead for copying an additional 1x to 2x
+ * the actual length of data, and a space overhead of an additional 2x to
+ * 3x the actual length.
+ */
 svn_error_t *
-svn_stringbuf_from_stream(svn_stringbuf_t **str,
+svn_stringbuf_from_stream(svn_stringbuf_t **result,
                           svn_stream_t *stream,
                           apr_size_t len_hint,
                           apr_pool_t *result_pool)
@@ -1508,7 +1518,7 @@ svn_stringbuf_from_stream(svn_stringbuf_
     }
 
   text->data[text->len] = '\0';
-  *str = text;
+  *result = text;
 
   return SVN_NO_ERROR;
 }