libfossil
fsl_buffer Struct Reference

A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid confusion with DB-side blobs. More...

#include "util.h"

Collaboration diagram for fsl_buffer:

Data Fields

fsl_size_t capacity
 Number of bytes allocated for this buffer.
fsl_size_t cursor
 Used by some routines to keep a cursor into this->mem.
int errCode
 When any buffer-related routines encounter an error, they set this flag so that the error can be propagated.
unsigned char * mem
 The raw memory pointed to by this buffer.
fsl_size_t used
 Number of "used" bytes in the buffer.

Detailed Description

A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid confusion with DB-side blobs.

Buffers are used extensively in fossil to do everything from reading files to compressing artifacts to creating dynamically-formatted strings. Because they are such a pervasive low-level type, and have such a simple structure, their members (unlike most other structs in this API) may be considered public and used directly by client code (as long as they do not mangle their state, e.g. by setting this->capacity smaller than this->used!).

General conventions of this class:

  • ALWAYS initialize them by copying fsl_buffer_empty or (depending on the context) fsl_buffer_empty_m. Failing to initialize them properly leads to undefined behaviour.
  • ALWAYS fsl_buffer_clear() buffers when done with them. Remember that failed routines which output to buffers might partially populate the buffer, so be sure to clean up in error cases.
  • The capacity member specifies how much memory the buffer currently holds in its mem member. If capacity is 0 and mem is not then the memory is expected to refer to used bytes of memory which are owned elsewhere. See fsl_buffer_external() and fsl_buffer_materialize() for details.
  • The used member specifies how much of the memory is actually "in use" by the buffer. The exact meaning of "used" is context-dependent but it's typically equivalent to the strlen() of the buffer's contents.
  • As a rule, the public APIs keep (used<capacity) and always (unless documented otherwise) tries to keep the memory buffer NUL-terminated (if it has any memory at all). The notable potential exception to that is that "external" buffers may not be NUL-terminated (see fsl_buffer_external()).
  • Use fsl_buffer_reuse() to keep memory around and reset the used amount to 0. Most library-wide routines which write to buffers will re-use that memory if they can, rather than re-allocating.

This example demonstrates the difference between used and capacity (error checking reduced to assert()ions for clarity):

// ALWAYS init via copying fsl_buffer_empty or (depending on
// the context) fsl_buffer_empty_m. The latter is used for
// in-struct initialization of struct members.
int rc = fsl_buffer_reserve(&b, 20);
assert(0==rc);
assert(b.capacity>=20); // it may reserve more!
assert(0==b.used);
rc = fsl_buffer_append(&b, "abc", 3);
assert(0==rc);
assert(3==b.used);
assert(0==b.mem[b.used]); // API always NUL-terminates
assert(0==b.used); // Resets the buffer but...
assert(b.capacity>=20); // ... keeps the memory.
fsl_buffer_clear(&b); // ALWAYS clean up
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
unsigned char * mem
The raw memory pointed to by this buffer.
Definition util.h:709
fsl_size_t used
Number of "used" bytes in the buffer.
Definition util.h:735
fsl_size_t capacity
Number of bytes allocated for this buffer.
Definition util.h:717
FSL_EXPORT int fsl_buffer_reserve(fsl_buffer *b, fsl_size_t n)
Reserves at least n bytes of capacity in buf.
FSL_EXPORT const fsl_buffer fsl_buffer_empty
Empty-initialized fsl_buffer instance, intended for copy initialization.
Definition util.h:769
FSL_EXPORT void fsl_buffer_clear(fsl_buffer *b)
Convenience equivalent of fsl_buffer_reserve(b,0).
FSL_EXPORT int fsl_buffer_append(fsl_buffer *b, void const *src, fsl_int_t n)
Appends the first n bytes of src, plus a NUL byte, to b, expanding b as necessary and incrementing b-...
FSL_EXPORT fsl_buffer * fsl_buffer_reuse(fsl_buffer *b)
If b is a managed buffer, this resets b->used, b->cursor, and b->mem[0] (if b->mem is not NULL) to 0.
See also
fsl_buffer_reserve()
fsl_buffer_resize()
fsl_buffer_external()
fsl_buffer_materialize()
fsl_buffer_append()
fsl_buffer_appendf()
fsl_buffer_cstr()
fsl_buffer_size()
fsl_buffer_capacity()
fsl_buffer_clear()
fsl_buffer_reuse()
fsl_buffer_err()
fsl_buffer_err_clear()

Definition at line 684 of file util.h.

Field Documentation

◆ capacity

fsl_size_t fsl_buffer::capacity

Number of bytes allocated for this buffer.

If capacity is 0 and this->mem is not NULL then this buffer's memory is assumed to be owned "elsewhere" and will be considered immutable by the API. Any attempt to modify it will result in a copy-on-write operation

Definition at line 717 of file util.h.

◆ cursor

fsl_size_t fsl_buffer::cursor

Used by some routines to keep a cursor into this->mem.

Note that a pointer-based cursor is not valid for some uses because mem can be reallocated (and thus moved).

Definition at line 741 of file util.h.

◆ errCode

int fsl_buffer::errCode

When any buffer-related routines encounter an error, they set this flag so that the error can be propagated.

Many APIs also become no-ops when this is set, the intention being to simplify many common uses of this class, e.g.:

if(fsl_buffer_err(b)) ...
FSL_EXPORT int fsl_buffer_err(fsl_buffer const *b)
Returns the current error code of the given buffer.

The alternative (without this member) being to check for an OOM error after every append operation.

Definition at line 759 of file util.h.

◆ mem

unsigned char* fsl_buffer::mem

The raw memory pointed to by this buffer.

There are two ways of using this member:

  • If this->capacity is non-0 then the first this->capacity bytes of this->mem are owned by this buffer instance. The API docs call this state "managed" buffers.
  • If this->capacity is 0 and this->mem is not NULL then the memory is owned by "somewhere else" and this API will treat it as immutable (so it may safely point to const data). Its lifetime must exceed this object's and any attempt made via this API to write to it will cause the memory to be copied (effectively a copy-on-write op). The API calls this state "external" buffers and refers to the copy-on-write of such buffers as "materializing" them. See fsl_buffer_external() and fsl_buffer_materialize() for details.

this->used bytes are treated as the "used" part of the buffer (as opposed to its capacity). When this->capacity>0 the difference beween (this->capacity - this->used) represents space the buffer has available for use before it will require another expansion/reallocation.

Definition at line 709 of file util.h.

◆ used

fsl_size_t fsl_buffer::used

Number of "used" bytes in the buffer.

This is generally interpreted as the string length of this->mem, and the buffer APIs which add data to a buffer always ensure that this->capacity is large enough to account for a trailing NUL byte in this->mem.

Library routines which manipulate buffers must ensure that (this->used<this->capacity) is always true, expanding the buffer if necessary. Much of the API assumes that precondition is always met, and any violation of it opens the code to undefined behaviour (which is okay, just don't ever break that precondition). Most APIs ensure that (used<capacity) is always true (as opposed to used<=capacity) because they add a trailing NUL byte which is not counted in the "used" length.

Definition at line 735 of file util.h.


The documentation for this struct was generated from the following file: