Specialize SBuf::reserveSpace and reserveCapacity functions to provide guarantee...

Tune SBuf::rawSpace() to take over from reserve* for the optimization role preveiously played by reserve*.
Adjust documentation and callers.

diff --git a/src/SBuf.cc b/src/SBuf.cc
index 9e76e4f4e23bf76935a773d65d856c1a9c5261e4..b49a40c5c4c19690d41526a81d11b09db7c6f3aa 100644 (file)
--- a/src/SBuf.cc
+++ b/src/SBuf.cc
@@ -187,23 +187,25 @@ SBuf::reserveCapacity(size_type minCapacity)
     cow(minCapacity);
 }
 
-void
-SBuf::reserveSpace(size_type minSpace)
+char *
+SBuf::rawSpace(size_type minSpace)
 {
     Must(0 <= minSpace); //upper bound checked in cow -> reAlloc
     debugs(24, 7, "reserving " << minSpace << " for " << id);
+    ++stats.rawAccess;
     // we're not concerned about RefCounts here,
     // the store knows the last-used portion. If
     // it's available, we're effectively claiming ownership
     // of it. If it's not, we need to go away (realloc)
     if (store_->canAppend(off_+len_, minSpace)) {
         debugs(24, 7, "not growing");
-        return;
+        return bufEnd();
     }
     // TODO: we may try to memmove before realloc'ing in order to avoid
     //   one allocation operation, if we're the sole owners of a MemBlob.
     //   Maybe some heuristic on off_ and length()?
-    reAlloc(estimateCapacity(minSpace+length()));
+    cow(minSpace+length());
+    return bufEnd();
 }
 
 void
@@ -274,7 +276,7 @@ SBuf::vappendf(const char *fmt, va_list vargs)
     Must(fmt != NULL);
 
     //reserve twice the format-string size, it's a likely heuristic
-    reserveSpace(strlen(fmt)*2);
+    rawSpace(strlen(fmt)*2);
 
     while (length() <= maxSize) {
 #ifdef VA_COPY
@@ -293,7 +295,7 @@ SBuf::vappendf(const char *fmt, va_list vargs)
         /* snprintf on FreeBSD returns at least free_space on overflows */
 
         if (sz >= static_cast<int>(store_->spaceSize()))
-            reserveSpace(sz*2); // TODO: tune heuristics
+            rawSpace(sz*2); // TODO: tune heuristics
         else if (sz < 0) // output error in vsnprintf
             throw TextException("output error in vsnprintf",__FILE__, __LINE__);
         else
@@ -465,14 +467,6 @@ SBuf::rawContent() const
     return buf();
 }
 
-char *
-SBuf::rawSpace(size_type minSize)
-{
-    cow(minSize+length());
-    ++stats.rawAccess;
-    return bufEnd();
-}
-
 void
 SBuf::forceSize(size_type newSize)
 {
@@ -857,7 +851,7 @@ SBuf::reAlloc(size_type newsize)
 SBuf&
 SBuf::lowAppend(const char * memArea, size_type areaSize)
 {
-    reserveSpace(areaSize); //called method also checks n <= maxSize()
+    rawSpace(areaSize); //called method also checks n <= maxSize()
     store_->append(memArea, areaSize);
     len_ += areaSize;
     ++stats.append;

diff --git a/src/SBuf.h b/src/SBuf.h
index e17677e67a74cabb14d1b88dc2fb91908c7146fd..fb65ca6f588d0f75cf53f9819a6083bfadbcb96e 100644 (file)
--- a/src/SBuf.h
+++ b/src/SBuf.h
@@ -340,19 +340,19 @@ public:
      * \warning Use with EXTREME caution, this is a dangerous operation.
      *
      * Returns a pointer to the first unused byte in the SBuf's storage,
-     * to be used for writing. If minsize is specified, it is guaranteed
-     * that at least minsize bytes will be available for writing. Otherwise
-     * it is guaranteed that at least as much storage as is currently
-     * available will be available for the call. A COW will be performed
-     * if necessary so that the returned pointer can be written to without
-     * unwanted side-effects.
-     * The returned pointer must not be stored, and will
+     * which can be be used for appending. At least minSize bytes will
+     * be available for writing.
+     * The returned pointer must not be stored by the caller, as it will
      * be invalidated by the first call to a non-const method call
      * on the SBuf.
-     * This call guarantees to never return NULL
+     * This call guarantees to never return NULL.
+     * This method can also be used to prepare the SBuf by preallocating a
+     * predefined amount of free space; this may help to optimize subsequent
+     * calls to SBuf::append or similar methods. In this case the returned
+     * pointer should be ignored.
      * \throw SBufTooBigException if the user tries to allocate too big a SBuf
      */
-    char *rawSpace(size_type minSize = npos);
+    char *rawSpace(size_type minSize);
 
     /** Force a SBuf's size
      * \warning use with EXTREME caution, this is a dangerous operation
@@ -407,13 +407,12 @@ public:
      *
      * After the reserveSpace request, the SBuf is guaranteed to have at
      * least minSpace bytes of unused backing store following the currently
-     * used portion until the next append operation to any of the SBufs
-     * sharing the backing MemBlob
+     * used portion and single ownership of the backing store.
      * \throw SBufTooBigException if the user tries to allocate too big a SBuf
      */
-    void reserveSpace(size_type minSpace);
+    void reserveSpace(size_type minSpace) {reserveCapacity(length()+minSpace);}
 
-    /** Request to resize the SBuf's store
+    /** Request to resize the SBuf's store capacity
      *
      * After this method is called, the SBuf is guaranteed to have at least
      * minCapacity bytes of total buffer size, including the currently-used