You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "aherbert (via GitHub)" <gi...@apache.org> on 2023/08/21 13:17:48 UTC

[GitHub] [commons-text] aherbert opened a new pull request, #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

aherbert opened a new pull request, #452:
URL: https://github.com/apache/commons-text/pull/452

   This fixes a performance regression where allocation was only using the exact size necessary for the additional chars (resulting in buffer reallocation on each append).


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] aherbert commented on a diff in pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "aherbert (via GitHub)" <gi...@apache.org>.
aherbert commented on code in PR #452:
URL: https://github.com/apache/commons-text/pull/452#discussion_r1300134930


##########
src/main/java/org/apache/commons/text/TextStringBuilder.java:
##########
@@ -1820,17 +1832,84 @@ public boolean endsWith(final String str) {
     /**
      * Tests the capacity and ensures that it is at least the size specified.
      *
+     * <p>Note: This method can be used to minimise memory reallocations during
+     * repeated addition of values by pre-allocating the character buffer.
+     * The method ignores a negative {@code capacity} argument.
+     *
      * @param capacity the capacity to ensure
      * @return this, to enable chaining
+     * @throws OutOfMemoryError if the capacity cannot be allocated
      */
     public TextStringBuilder ensureCapacity(final int capacity) {
-        // checks for overflow
-        if (capacity > 0 && capacity - buffer.length > 0) {
-            reallocate(capacity);
+        if (capacity > 0) {
+            ensureCapacityInternal(capacity);
         }
         return this;
     }
 
+    /**
+     * Ensure that the buffer is at least the size specified. The {@code capacity} argument
+     * is treated as an unsigned integer.
+     *
+     * <p>This method will raise an {@link OutOfMemoryError} if the capacity is too large
+     * for an array, or cannot be allocated.
+     *
+     * @param capacity the capacity to ensure
+     * @throws OutOfMemoryError if the capacity cannot be allocated
+     */
+    private void ensureCapacityInternal(final int capacity) {
+        // Check for overflow of the current buffer.
+        // Assumes capacity is an unsigned integer up to Integer.MAX_VALUE * 2
+        // (the largest possible addition of two maximum length arrays).
+        if (capacity - buffer.length > 0) {
+            resizeBuffer(capacity);
+        }
+    }
+
+    /**
+     * Resizes the buffer to at least the size specified.
+     *
+     * @param minCapacity the minimum required capacity
+     * @throws OutOfMemoryError if the {@code minCapacity} is negative
+     */
+    private void resizeBuffer(final int minCapacity) {
+        // Overflow-conscious code treats the min and new capacity as unsigned.
+        final int oldCapacity = buffer.length;
+        int newCapacity = oldCapacity * 2;
+        if (Integer.compareUnsigned(newCapacity, minCapacity) < 0) {
+            newCapacity = minCapacity;
+        }
+        if (Integer.compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) {
+            newCapacity = createPositiveCapacity(minCapacity);
+        }
+        reallocate(newCapacity);
+    }
+
+    /**
+     * Create a positive capacity at least as large the minimum required capacity.
+     * If the minimum capacity is negative then this throws an OutOfMemoryError as no array
+     * can be allocated.
+     *
+     * @param minCapacity the minimum capacity
+     * @return the capacity
+     * @throws OutOfMemoryError if the {@code minCapacity} is negative
+     */
+    private static int createPositiveCapacity(final int minCapacity) {
+        if (minCapacity < 0) {
+            // overflow
+            throw new OutOfMemoryError("Unable to allocate array size: " + Integer.toUnsignedString(minCapacity));

Review Comment:
   We throw an OOM in the code I adapted from Commons Codec. Disclaimer: I wrote that code so I am only copying my own precedent. However this is the behaviour of JDK's StringBuilder. If you try to add to an array such that it would not fit in a single array you will get an OutOfMemoryError. Since we are billing the TextStringBuilder as a replacement for that then it seems appropriate to copy the behaviour.
   
   Regarding recovery by the user. This would be a situation where you are adding to the StringBuilder and then you get an out-of-memory error. So you have a situation where a builder cannot create a single String to hold all the data. The recovery is to either try to process smaller chunks of the full chars; or accept that you have to truncate the single String. If we start throwing e.g. IAE here then a user will not be able to use the same try-catch with our object that they use with a JDK StringBuilder. The catch must be modified and we lose the drop-in-replacement pattern.
   
   Note: I just updated my extra tests to use JDK's StringBuilder. They pass.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] garydgregory merged pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory merged PR #452:
URL: https://github.com/apache/commons-text/pull/452


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] aherbert commented on pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "aherbert (via GitHub)" <gi...@apache.org>.
aherbert commented on PR #452:
URL: https://github.com/apache/commons-text/pull/452#issuecomment-1686385855

   The memory tests that check the new capacity functions are not running on GH. I do not know if apache has access to larger runners. The standard [linux runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)  have 7GB and 2 CPU. The smallest test should be fine with 7GB but for some reason the test is still skipped. It may be due to forking within the surefire-plugin and limitations for the test env.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] garydgregory commented on a diff in pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory commented on code in PR #452:
URL: https://github.com/apache/commons-text/pull/452#discussion_r1300107300


##########
src/main/java/org/apache/commons/text/TextStringBuilder.java:
##########
@@ -1820,17 +1832,84 @@ public boolean endsWith(final String str) {
     /**
      * Tests the capacity and ensures that it is at least the size specified.
      *
+     * <p>Note: This method can be used to minimise memory reallocations during
+     * repeated addition of values by pre-allocating the character buffer.
+     * The method ignores a negative {@code capacity} argument.
+     *
      * @param capacity the capacity to ensure
      * @return this, to enable chaining
+     * @throws OutOfMemoryError if the capacity cannot be allocated
      */
     public TextStringBuilder ensureCapacity(final int capacity) {
-        // checks for overflow
-        if (capacity > 0 && capacity - buffer.length > 0) {
-            reallocate(capacity);
+        if (capacity > 0) {
+            ensureCapacityInternal(capacity);
         }
         return this;
     }
 
+    /**
+     * Ensure that the buffer is at least the size specified. The {@code capacity} argument
+     * is treated as an unsigned integer.
+     *
+     * <p>This method will raise an {@link OutOfMemoryError} if the capacity is too large
+     * for an array, or cannot be allocated.
+     *
+     * @param capacity the capacity to ensure
+     * @throws OutOfMemoryError if the capacity cannot be allocated
+     */
+    private void ensureCapacityInternal(final int capacity) {
+        // Check for overflow of the current buffer.
+        // Assumes capacity is an unsigned integer up to Integer.MAX_VALUE * 2
+        // (the largest possible addition of two maximum length arrays).
+        if (capacity - buffer.length > 0) {
+            resizeBuffer(capacity);
+        }
+    }
+
+    /**
+     * Resizes the buffer to at least the size specified.
+     *
+     * @param minCapacity the minimum required capacity
+     * @throws OutOfMemoryError if the {@code minCapacity} is negative
+     */
+    private void resizeBuffer(final int minCapacity) {
+        // Overflow-conscious code treats the min and new capacity as unsigned.
+        final int oldCapacity = buffer.length;
+        int newCapacity = oldCapacity * 2;
+        if (Integer.compareUnsigned(newCapacity, minCapacity) < 0) {
+            newCapacity = minCapacity;
+        }
+        if (Integer.compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) {
+            newCapacity = createPositiveCapacity(minCapacity);
+        }
+        reallocate(newCapacity);
+    }
+
+    /**
+     * Create a positive capacity at least as large the minimum required capacity.
+     * If the minimum capacity is negative then this throws an OutOfMemoryError as no array
+     * can be allocated.
+     *
+     * @param minCapacity the minimum capacity
+     * @return the capacity
+     * @throws OutOfMemoryError if the {@code minCapacity} is negative
+     */
+    private static int createPositiveCapacity(final int minCapacity) {
+        if (minCapacity < 0) {
+            // overflow
+            throw new OutOfMemoryError("Unable to allocate array size: " + Integer.toUnsignedString(minCapacity));

Review Comment:
   Hi @aherbert 
   Thank you for this PR :-)
   I think this should be an `IllegalArgumentException` because the JVM has NOT in fact run out of memory and a call site up the stack may be able to recover from the situation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] codecov-commenter commented on pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #452:
URL: https://github.com/apache/commons-text/pull/452#issuecomment-1686316320

   ## [Codecov](https://app.codecov.io/gh/apache/commons-text/pull/452?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
   > Merging [#452](https://app.codecov.io/gh/apache/commons-text/pull/452?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) (4faa0e1) into [master](https://app.codecov.io/gh/apache/commons-text/commit/efa7475c3da2153a0d3a769dac8f5fe606c2b9fb?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) (efa7475) will **decrease** coverage by `0.03%`.
   > The diff coverage is `95.23%`.
   
   ```diff
   @@             Coverage Diff              @@
   ##             master     #452      +/-   ##
   ============================================
   - Coverage     97.13%   97.11%   -0.03%     
   - Complexity     2332     2337       +5     
   ============================================
     Files            84       84              
     Lines          5769     5783      +14     
     Branches        936      938       +2     
   ============================================
   + Hits           5604     5616      +12     
   - Misses           87       88       +1     
   - Partials         78       79       +1     
   ```
   
   
   | [Files Changed](https://app.codecov.io/gh/apache/commons-text/pull/452?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Coverage Δ | |
   |---|---|---|
   | [...ava/org/apache/commons/text/TextStringBuilder.java](https://app.codecov.io/gh/apache/commons-text/pull/452?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3JjL21haW4vamF2YS9vcmcvYXBhY2hlL2NvbW1vbnMvdGV4dC9UZXh0U3RyaW5nQnVpbGRlci5qYXZh) | `97.53% <95.23%> (-0.21%)` | :arrow_down: |
   
   :mega: We’re building smart automated test selection to slash your CI/CD build times. [Learn more](https://about.codecov.io/iterative-testing/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [commons-text] garydgregory commented on pull request #452: TEXT-228: Fix TextStringBuilder to over-allocate when ensuring capacity

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory commented on PR #452:
URL: https://github.com/apache/commons-text/pull/452#issuecomment-1687038018

   https://issues.apache.org/jira/projects/TEXT/issues/TEXT-228


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org