2525#include < string>
2626#include < type_traits>
2727
28+ #include " arrow/memory_pool.h"
2829#include " arrow/status.h"
2930#include " arrow/util/bit-util.h"
3031#include " arrow/util/macros.h"
3132#include " arrow/util/visibility.h"
3233
3334namespace arrow {
3435
35- class MemoryPool ;
36-
3736// ----------------------------------------------------------------------
3837// Buffer classes
3938
40- // / Immutable API for a chunk of bytes which may or may not be owned by the
41- // / class instance.
39+ // / \class Buffer
40+ // / \brief Object containing a pointer to a piece of contiguous memory with a
41+ // / particular size. Base class does not own its memory
4242// /
4343// / Buffers have two related notions of length: size and capacity. Size is
4444// / the number of bytes that might have valid data. Capacity is the number
@@ -133,7 +133,8 @@ ARROW_EXPORT
133133std::shared_ptr<Buffer> SliceMutableBuffer (const std::shared_ptr<Buffer>& buffer,
134134 const int64_t offset, const int64_t length);
135135
136- // / A Buffer whose contents can be mutated. May or may not own its data.
136+ // / \class MutableBuffer
137+ // / \brief A Buffer whose contents can be mutated. May or may not own its data.
137138class ARROW_EXPORT MutableBuffer : public Buffer {
138139 public:
139140 MutableBuffer (uint8_t * data, const int64_t size) : Buffer(data, size) {
@@ -148,6 +149,8 @@ class ARROW_EXPORT MutableBuffer : public Buffer {
148149 MutableBuffer () : Buffer(NULLPTR, 0 ) {}
149150};
150151
152+ // / \class ResizableBuffer
153+ // / \brief A mutable buffer that can be resized
151154class ARROW_EXPORT ResizableBuffer : public MutableBuffer {
152155 public:
153156 // / Change buffer reported size to indicated size, allocating memory if
@@ -190,13 +193,22 @@ class ARROW_EXPORT PoolBuffer : public ResizableBuffer {
190193 MemoryPool* pool_;
191194};
192195
196+ // / \class BufferBuilder
197+ // / \brief A class for incrementally building a contiguous chunk of in-memory data
193198class ARROW_EXPORT BufferBuilder {
194199 public:
195- explicit BufferBuilder (MemoryPool* pool)
200+ explicit BufferBuilder (MemoryPool* pool ARROW_MEMORY_POOL_DEFAULT )
196201 : pool_(pool), data_(NULLPTR), capacity_(0 ), size_(0 ) {}
197202
198- // / Resizes the buffer to the nearest multiple of 64 bytes per Layout.md
199- Status Resize (const int64_t elements) {
203+ // / \brief Resizes the buffer to the nearest multiple of 64 bytes
204+ // /
205+ // / \param elements the new capacity of the of the builder. Will be rounded
206+ // / up to a multiple of 64 bytes for padding
207+ // / \param shrink_to_fit if new capacity smaller than existing size,
208+ // / reallocate internal buffer. Set to false to avoid reallocations when
209+ // / shrinking the builder
210+ // / \return Status
211+ Status Resize (const int64_t elements, bool shrink_to_fit = true ) {
200212 // Resize(0) is a no-op
201213 if (elements == 0 ) {
202214 return Status::OK ();
@@ -205,7 +217,7 @@ class ARROW_EXPORT BufferBuilder {
205217 buffer_ = std::make_shared<PoolBuffer>(pool_);
206218 }
207219 int64_t old_capacity = capacity_;
208- RETURN_NOT_OK (buffer_->Resize (elements));
220+ RETURN_NOT_OK (buffer_->Resize (elements, shrink_to_fit ));
209221 capacity_ = buffer_->capacity ();
210222 data_ = buffer_->mutable_data ();
211223 if (capacity_ > old_capacity) {
@@ -214,7 +226,14 @@ class ARROW_EXPORT BufferBuilder {
214226 return Status::OK ();
215227 }
216228
217- Status Append (const uint8_t * data, int64_t length) {
229+ // / \brief Ensure that builder can accommodate the additional number of bytes
230+ // / without the need to perform allocations
231+ // /
232+ // / \param size number of additional bytes to make space for
233+ // / \return Status
234+ Status Reserve (const int64_t size) { return Resize (size_ + size, false ); }
235+
236+ Status Append (const void * data, int64_t length) {
218237 if (capacity_ < length + size_) {
219238 int64_t new_capacity = BitUtil::NextPower2 (length + size_);
220239 RETURN_NOT_OK (Resize (new_capacity));
@@ -248,7 +267,7 @@ class ARROW_EXPORT BufferBuilder {
248267 }
249268
250269 // Unsafe methods don't check existing size
251- void UnsafeAppend (const uint8_t * data, int64_t length) {
270+ void UnsafeAppend (const void * data, int64_t length) {
252271 memcpy (data_ + size_, data, static_cast <size_t >(length));
253272 size_ += length;
254273 }
0 commit comments