al(3) Assembly Line al(3)NAME
OSSP al - Assembly Line
VERSION
OSSP al 0.9.2 (03-Oct-2005)
SYNOPSIS
Abstract Data Types:
al_rc_t, al_t, al_tx_t, al_td_t, al_chunk_t.
Assembly Line Operations:
al_create, al_destroy, al_append_bytes, al_prepend_bytes,
al_attach_buffer, al_splice, al_setlabel, al_bytes.
Traversal Operations:
al_txalloc, al_txfree, al_traverse, al_traverse_next, al_tra‐
verse_end, al_traverse_cb.
Convenience Operations:
al_flatten, al_copy, al_firstlabel, al_spanlabel.
Chunk Operations:
al_chunk_len, al_chunk_span, al_chunk_label, al_same_label,
al_chunk_ptr.
Error Handling:
al_error.
DESCRIPTION
OSSP al defines an abstract data type of a data buffer that can assem‐
ble, move and truncate chunks of data in a stream but avoids actual
copying. It was built to deal efficiently with communication streams
between software modules. It especially provides flexible semantical
data attribution through by-chunk labeling. It also has convenient
chunk traversal methods and optional OSSP ex based exception handling.
DATA TYPES
OSSP al uses six data types in its API:
al_rc_t (Return Code Type)
This is an exported enumerated integer type with the following pos‐
sible values:
AL_OK Everything Ok
AL_ERR_ARG Invalid Argument
AL_ERR_MEM Not Enough Memory
AL_ERR_EOF End Of Communication
AL_ERR_INT Internal Error
al_t (Assembly Line Type)
This is an opaque data type representing a data buffer. Only
pointers to this abstract data type are used in the API.
al_label_t (Label Type)
This is an opaque pointer type representing a specific data
flavour. You can restrict traversal operations to data that was
marked with the specific flavour. Usually you would cast a pointer
to the object that maintains the data to al_label_t. You may use
NULL as a label but on traversal NULL matches any label.
al_tx_t (Traversal Context Type)
This is an opaque data type representing the state of a buffer tra‐
versal operation. Only pointers to this abstract data type are used
in the API.
al_td_t (Traversal Direction Type)
This is an exported enumerated integer type with the following pos‐
sible values:
AL_FORWARD traverse assembly line from beginning to end
AL_BACKWARD traverse assembly line from end to beginning
AL_FORWARD_SPAN like AL_FORWARD, but stop when label does not match
AL_BACKWARD_SPAN like AL_BACKWARD, but stop when label does not match
al_chunk_t (Chunk Type)
This is an opaque data type representing a chunk of a buffer during
a traversal operation. Only pointers to this abstract data type are
used in the API. The al_chunk_t type is used to generate a pointer
and byte count to access the data in the buffer.
FUNCTIONS
OSSP al provides a bunch of API functions, all modelled after the same
prototype: "al_rc_t al_name(al_[chunk]_t *, ...)". This means every
function returns al_rc_t to indicate its success (AL_OK) or failure
(AL_ERR_XXX) by returning a return code (the corresponding describing
text can be determined by passing this return code to al_error). Each
function name starts with the common prefix al_ and receives a al_t (or
al_chunk_t) object on which it operates as its first argument.
Assembly Line Operations
al_rc_t al_create(al_t **alp);
Create an assembly line abstraction object. The object is stored
in alp on success.
Example: al_t *al; al_create(&al);
al_rc_t al_destroy(al_t *al);
Destroy an assembly line abstraction object. The object al is
invalid after this call succeeded.
Example: al_destroy(al);
al_rc_t al_append_bytes(al_t *al, const char *src, size_t n, al_label_t
label);
Append n bytes from a storage array at src to the assembly line.
The bytes are copied, memory is allocated as necessary. The data is
tagged with label.
Example: al_append_bytes(al, "Goodbye cruel world\n", 20, NULL);
al_rc_t al_prepend_bytes(al_t *al, const char *src, size_t n,
al_label_t label);
Prepend n bytes from a storage array at src to the assembly line.
The bytes are copied, memory is allocated as necessary.
Example: al_prepend_bytes(al, "Hello world\n", 12, NULL);
al_rc_t al_attach_buffer(al_t *al, char *p, size_t n, al_label_t label,
void (*freemem)(char *, size_t, void *), void *u);
Attach the storage array starting at p with size n at the end of
the assembly line. Its content becomes part of the assembly line
and is subject to assembly line operations. The storage array must
stay in scope until it is no longer referenced by the assembly
line. When this happens the function freemem is called with the
original pointer p, size n and an arbitrary pointer u. Passing a
NULL pointer for freemem is valid, then no callback takes place,
which might be appropriate for static buffers.
Example: char store[] = "foo\n"; al_attach_buffer(al, store,
sizeof(store), NULL, NULL, NULL);
al_rc_t al_splice(al_t *al, size_t off, size_t n, al_t *nal, al_t
*tal);
This is the general data move operation modelled after the perl
operator splice.
off and n are byte counts that define a span of bytes within the
source assembly line al. These bytes are moved to the target assem‐
bly line tal while the content of the new assembly line nal is
moved to the source to replace the selected span.
There are two deviations from the Perl operator to avoid copying:
The move to the target assembly line tal appends the data to its
end. The move from the new assembly line nal removes the data from
its origin.
The target assembly line tal may be NULL, the data bytes that would
be moved to the target are then discarded. This avoids creation and
destruction of a dummy target.
The new assembly line nal may be NULL, then nothing is inserted
into the source. This avoids creation and destruction of an empty
assembly line.
Examples:
al_t *source;
al_t *insertion;
al_t *buffer;
al_create(&source);
al_create(&insertion);
al_create(&buffer);
al_append_bytes(source, "Hello world\n", 12, NULL);
al_append_bytes(insertion, "Goodbye cruel", 13, NULL);
al_splice(source, 0, 5, insertion, buffer);
The buffer now holds the string "Hello". The source now holds the
string "Goodbye cruel world\n". The insertion is now empty.
al_append_bytes(insertion, "brave", 5, NULL);
al_splice(source, 8, 5, insertion, NULL);
The source now holds the string "Goodbye brave world\n". The
insertion is now empty.
al_append_bytes(insertion, "B", 1, NULL);
al_splice(source, 0, 8, NULL, buffer);
al_splice(source, 0, 1, insertion, NULL);
al_append_bytes(insertion, "\n", 1, NULL);
al_splice(buffer, al_bytes(buffer)-1, 1, insertion, NULL),
The source now holds the string "Brave world\n". The buffer now
holds the string "HelloGoodbye\n". The insertion is empty.
al_rc_t al_setlabel(al_t *al, size_t off, size_t n, al_label_t oldla‐
bel, al_label_t newlabel);
off and n are byte counts that define a span of bytes within the
source assembly line al. The bytes within that span that match old‐
label are tagged with newlabel, any existing labels for these bytes
are overwritten.
size_t al_bytes(const al_t *al);
Returns the number of bytes stored in the assembly line.
Example: al_t *al; size_t count; count = al_bytes(al);
Traversal Operations
al_rc_t al_txalloc(al_t *al, al_tx_t **txp);
Allocate a traversal context.
Example: al_tx_t *tx; al_txalloc(&tx);
al_rc_t al_txfree(al_t *al, al_tx_t *tx);
Free a traversal context.
Example: al_tx_t *tx; al_txfree(tx);
al_rc_t al_traverse(al_t *al, size_t off, size_t n, al_td_t dir,
al_label_t label, al_tx_t *tx);
Start traversing the assembly line al beginning at byte offset off
for up to n bytes in direction dir. If label is not NULL then you
will see only data that was tagged with label. The state of the
traversal is stored in the supplied context tx.
This function fails when the offset is outside the assembly line
bounds.
al_rc_t al_traverse_next(al_t *al, al_tx_t *tx, al_chunk_t **alcp);
Complete a traversal step on the assembly line al using the ini‐
tialized context tx. In each step a chunk descriptor is filled and
stored in alcp. All bytes of the chunk are guaranteed to be stored
in a flat array and can be accessed through the chunk operations
described below.
The function returns AL_ERR_EOF when it passes the end (or begin‐
ning in case of backward traversal) of the assembly line.
al_rc_t al_traverse_end(al_t *al, al_tx_t *tx, int final);
Clean up internal state of traversal. If final is zero, you may
continue the traversal later by calling al_traverse_next. If final
is non-zero you need to start a new traversal. It is mandatory that
every traversal that was started is finished by a call to al_tra‐
verse_end with final set to a non-zero value.
al_rc_t al_traverse_cb(al_t *al, size_t off, size_t n, al_td_t dir,
al_label_t label, al_rc_t (*cb)(al_chunk_t *, void *), void *u);
al_traverse_cb is a wrapper function that does a full assembly line
traversal in a single call. In every step a chunk descriptor is
passed to the callback function cb together with a user supplied
pointer u. When the callback function returns AL_OK the traversal
continues, when it returns AL_ERR_EOF the traversal is aborted and
AL_OK is returned to the original caller. Any other return code
returned by the callback is passed to the original caller verbatim.
Convenience Operations
al_rc_t al_flatten(al_t *al, size_t off, size_t n, al_td_t dir, char
*dst, size_t *lenp);
off and n are byte counts that define a span of bytes with the
assembly line al. These bytes are copied to the storage array dst
which must be sized appropriately. off must be a valid offset, n
must be positive but may exceed the size of the assembly line. The
actual number of bytes that is copied to the destination is stored
in lenp. If dst is NULL then no data is copied but the number of
bytes is still counted in lenp. This can be used to precalculate
the size of the needed storage array by passing an arbitrary high
maximum size as n. If dir denotes a backwards traversal the stor‐
age array is filled from its end.
Example:
al_t *al;
char buffer[42];
size_t actual;
al_flatten(al, 500, 42, AL_FORWARD, buffer, &actual);
al_rc_t al_copy(al_t *al, size_t off, size_t n, al_td_t dir, al_t
*tal);
off and n are byte counts that define a span of bytes within the
assembly line al. These bytes are appended to the target assembly
line tal, memory is allocated as necessary. off must be a valid
offset, n must be positive but may exceed the size of the assembly
line.
Example:
al_t *al;
al_t *tal;
al_create(&tal);
al_flatten(al, 500, 42, tal);
al_rc_t al_firstlabel(al_t *al, size_t off, size_t n, al_td_t dir,
al_label_t *labelp);
off and n are byte counts that define a span of bytes within the
assembly line al. The label that was attached to the first byte
within the defined span is stored in labelp, otherwise al_firstla‐
bel returns an error.
al_rc_t al_spanlabel(al_t *al, size_t off, size_t n, al_label_t *label,
size_t *<offp>, size_t *<spanp>);
off and n are byte counts that define a span of bytes within the
assembly line al. This span is searched for data tagged with the
label. The absolute byte offset of the first byte matching the
label and the length of the span of the same label is returned in
offp and spanp respectively.
Chunk Operations
size_t al_chunk_len(al_chunk_t *alc);
Returns the number of bytes in a chunk.
size_t al_chunk_span(al_chunk_t *alc, size_t off, size_t n);
off and n are byte counts that define a span of bytes.
al_chunk_span returns the number of bytes that are stored in the
chunk. off must be a valid offset, n must be positive but may
exceed the size of the chunk.
al_label_t al_chunk_label(al_chunk_t *alc);
Return the label that was used to tag the data in alc. This can be
NULL.
int al_same_label(al_chunk_t *alc, al_label_t *label);
Return true if label matches the label that was used to tag the
data in alc. A NULL label matches everything.
char *al_chunk_ptr(al_chunk_t *alc, size_t off);
Returns the pointer to the byte at offset off within the chunk alc.
off must be positive and must not exceed the size of the chunk.
Since all bytes of the chunk are guaranteed to be stored in a flat
array the pointer can be used to reference every byte within the
chunk.
Example:
al_chunk_t *alc;
char *start, *end;
start = al_chunk_ptr(alc, 0);
end = start + al_chunk_len(alc) - 1;
Error Handling
const char *al_error(al_rc_t rv);
Retrieve a string that describes the return code rv in english.
SEE ALSOHISTORY
OSSP al was invented in October 2002 by Michael van Elst <mlelstv@ser‐
pens.de> under contract with Cable & Wireless Germany
<http://www.cw.com/de> for use inside the OSSP project
<http://www.ossp.org/>.
AUTHORS
Michael van Elst
mlelstv@serpens.de
03-Oct-2005 OSSP al 0.9.2 al(3)
