class CordBuffer

Creates an empty CordBuffer.

Destroys this CordBuffer instance and, if not empty, releases any memory

managed by this instance, invalidating previously returned references.

CordBuffer is move-only

CordBuffer::MaximumPayload()

Returns the guaranteed maximum payload for a CordBuffer returned by the

`CreateWithDefaultLimit()` method. While small, each internal buffer inside

a Cord incurs an overhead to manage the length, type and reference count

for the buffer managed inside the cord tree. Applications can use this

method to get approximate number of buffers required for a given byte

size, etc.

For example:

const size_t payload = absl::CordBuffer::MaximumPayload();

const size_t buffer_count = (total_size + payload - 1) / payload;

buffers.reserve(buffer_count);

Overload to the above `MaximumPayload()` except that it returns the

maximum payload for a CordBuffer returned by the `CreateWithCustomLimit()`

method given the provided `block_size`.

CordBuffer::CreateWithDefaultLimit()

Creates a CordBuffer instance of the desired `capacity`, capped at the

default limit `kDefaultLimit`. The returned buffer has a guaranteed

capacity of at least `min(kDefaultLimit, capacity)`. See the class comments

for more information on buffer capacities and intended usage.

CordBuffer::CreateWithCustomLimit()

Creates a CordBuffer instance of the desired `capacity` rounded to an

appropriate power of 2 size less than, or equal to `block_size`.

Requires `block_size` to be a power of 2.

If `capacity` is less than or equal to `kDefaultLimit`, then this method

behaves identical to `CreateWithDefaultLimit`, which means that the caller

is guaranteed to get a buffer of at least the requested capacity.

If `capacity` is greater than or equal to `block_size`, then this method

returns a buffer with an `allocated size` of `block_size` bytes. Otherwise,

this methods returns a buffer with a suitable smaller power of 2 block size

to satisfy the request. The actual size depends on a number of factors, and

is typically (but not necessarily) the highest or second highest power of 2

value less than or equal to `capacity`.

The 'allocated size' includes a small amount of overhead required for

internal state, which is currently 13 bytes on 64-bit platforms. For

example: a buffer created with `block_size` and `capacity' set to 8KiB

will have an allocated size of 8KiB, and an effective internal `capacity`

of 8KiB - 13 = 8179 bytes.

To demonstrate this in practice, let's assume we want to read data from

somewhat larger files using approximately 64KiB buffers:

absl::Cord ReadFromFile(int fd, size_t n) {

absl::Cord cord;

while (n > 0) {

CordBuffer buffer = CordBuffer::CreateWithCustomLimit(64

<

<

10, n);

absl::Span

<char

> data = buffer.available_up_to(n);

ReadFileDataOrDie(fd, data.data(), data.size());

buffer.IncreaseLengthBy(data.size());

cord.Append(std::move(buffer));

n -= data.size();

}

return cord;

}

If we'd use this function to read a file of 659KiB, we may get the

following pattern of allocated cord buffer sizes:

CreateWithCustomLimit(64KiB, 674816) --> ~64KiB (65523)

CreateWithCustomLimit(64KiB, 674816) --> ~64KiB (65523)

...

CreateWithCustomLimit(64KiB, 19586) --> ~16KiB (16371)

CreateWithCustomLimit(64KiB, 3215) --> 3215 (at least 3215)

The reason the method returns a 16K buffer instead of a roughly 19K buffer

is to reduce memory overhead and fragmentation risks. Using carefully

chosen power of 2 values reduces the entropy of allocated memory sizes.

Additionally, let's assume we'd use the above function on files that are

generally smaller than 64K. If we'd use 'precise' sized buffers for such

files, than we'd get a very wide distribution of allocated memory sizes

rounded to 4K page sizes, and we'd end up with a lot of unused capacity.

In general, application should only use custom sizes if the data they are

consuming or storing is expected to be many times the chosen block size,

and be based on objective data and performance metrics. For example, a

compress function may work faster and consume less CPU when using larger

buffers. Such an application should pick a size offering a reasonable

trade-off between expected data size, compute savings with larger buffers,

and the cost or fragmentation effect of larger buffers.

Applications must pick a reasonable spot on that curve, and make sure their

data meets their expectations in size distributions such as "mostly large".

CordBuffer::available()

Returns the span delineating the available capacity in this buffer

which is defined as `{ data() + length(), capacity() - length() }`.

CordBuffer::available_up_to()

Returns the span delineating the available capacity in this buffer limited

to `size` bytes. This is equivalent to `available().subspan(0, size)`.

CordBuffer::data()

Returns a non-null reference to the data managed by this instance.

Applications are allowed to write up to `capacity` bytes of instance data.

CordBuffer data is uninitialized by default. Reading data from an instance

that has not yet been initialized will lead to undefined behavior.

CordBuffer::length()

Returns the length of this instance. The default length of a CordBuffer is

0, indicating an 'empty' CordBuffer. Applications must specify the length

of the data in a CordBuffer before adding it to a Cord.

CordBuffer::capacity()

Returns the capacity of this instance. All instances have a non-zero

capacity: default and `moved from` instances have a small internal buffer.

CordBuffer::IncreaseLengthBy()

Increases the length of this buffer by the specified 'n' bytes.

Applications must make sure all data in this buffer up to the new length

has been initialized before adding a CordBuffer to a Cord: failure to do so

will lead to undefined behavior. Requires `length() + n

<

= capacity()`.

Typically, applications will use 'available_up_to()` to get a span of the

desired capacity, and use `span.size()` to increase the length as in:

absl::Span

<char

> span = buffer.available_up_to(desired);

buffer.IncreaseLengthBy(span.size());

memcpy(span.data(), src, span.size());

etc...

CordBuffer::SetLength()

Sets the data length of this instance. Applications must make sure all data

of the specified length has been initialized before adding a CordBuffer to

a Cord: failure to do so will lead to undefined behavior.

Setting the length to a small value or zero does not release any memory

held by this CordBuffer instance. Requires `length

<

= capacity()`.

Applications should preferably use the `IncreaseLengthBy()` method above

in combination with the 'available()` or `available_up_to()` methods.