This is an automated email from the ASF dual-hosted git repository.
jbonofre pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-java.git
The following commit(s) were added to refs/heads/main by this push:
new 776466e90 GH-141: Correct capacity behavior in BufferAllocator.buffer
docstrings (#1010)
776466e90 is described below
commit 776466e904f3ae44f52c3baa019e795e8a68c527
Author: Aleksei Starikov <[email protected]>
AuthorDate: Sun Feb 8 14:08:20 2026 +0100
GH-141: Correct capacity behavior in BufferAllocator.buffer docstrings
(#1010)
## What's Changed
Update the `BufferAllocator.buffer(long)` and
`BufferAllocator.buffer(long, BufferManager)` docstrings so they match
the actual behavior: the returned buffer’s capacity is the allocated
(possibly rounded) size, not the requested size. The previous text said
the capacity would be set to the configured size, which was incorrect.
The new text also mentions that callers can use
`ArrowBuf#capacity(long)` to set the capacity to the requested size when
needed.
Documentation-only change; no code or behavioral changes.
Closes #141.
---
.../src/main/java/org/apache/arrow/memory/ArrowBuf.java | 2 +-
.../main/java/org/apache/arrow/memory/BufferAllocator.java | 14 ++++++++------
2 files changed, 9 insertions(+), 7 deletions(-)
diff --git
a/memory/memory-core/src/main/java/org/apache/arrow/memory/ArrowBuf.java
b/memory/memory-core/src/main/java/org/apache/arrow/memory/ArrowBuf.java
index 775a8925a..b8012fe64 100644
--- a/memory/memory-core/src/main/java/org/apache/arrow/memory/ArrowBuf.java
+++ b/memory/memory-core/src/main/java/org/apache/arrow/memory/ArrowBuf.java
@@ -136,7 +136,7 @@ public final class ArrowBuf implements AutoCloseable {
/**
* Adjusts the capacity of this buffer. Size increases are NOT supported.
*
- * @param newCapacity Must be in in the range [0, length).
+ * @param newCapacity Must be in the range [0, length).
*/
public synchronized ArrowBuf capacity(long newCapacity) {
diff --git
a/memory/memory-core/src/main/java/org/apache/arrow/memory/BufferAllocator.java
b/memory/memory-core/src/main/java/org/apache/arrow/memory/BufferAllocator.java
index 4f9d3c61c..dbd6da329 100644
---
a/memory/memory-core/src/main/java/org/apache/arrow/memory/BufferAllocator.java
+++
b/memory/memory-core/src/main/java/org/apache/arrow/memory/BufferAllocator.java
@@ -25,9 +25,10 @@ import org.checkerframework.checker.nullness.qual.Nullable;
public interface BufferAllocator extends AutoCloseable {
/**
- * Allocate a new or reused buffer of the provided size. Note that the
buffer may technically be
- * larger than the requested size for rounding purposes. However, the
buffer's capacity will be
- * set to the configured size.
+ * Allocate a new or reused buffer of the provided size. The buffer may be
larger than the
+ * requested size for rounding purposes (e.g. to a power of two), and the
buffer's capacity will
+ * reflect the actual allocated size. Use {@link ArrowBuf#capacity(long)} to
set the capacity to
+ * the requested size if needed.
*
* @param size The size in bytes.
* @return a new ArrowBuf, or null if the request can't be satisfied
@@ -36,9 +37,10 @@ public interface BufferAllocator extends AutoCloseable {
ArrowBuf buffer(long size);
/**
- * Allocate a new or reused buffer of the provided size. Note that the
buffer may technically be
- * larger than the requested size for rounding purposes. However, the
buffer's capacity will be
- * set to the configured size.
+ * Allocate a new or reused buffer of the provided size. The buffer may be
larger than the
+ * requested size for rounding purposes (e.g. to a power of two), and the
buffer's capacity will
+ * reflect the actual allocated size. Use {@link ArrowBuf#capacity(long)} to
set the capacity to
+ * the requested size if needed.
*
* @param size The size in bytes.
* @param manager A buffer manager to manage reallocation.
