libporty - the util package
The util package is a collection of utility calls not directlt related
to porting. These calls are used by the high level layer of libporty.
To avoid bloating the util package, the policy is that no "usefully
looking", "the user may often need this" calls are added. Instead,
only the minimal subset of calls that are really required for the high
level layer of libporty is supported.
libporty/util/argv.h
When doing network communication, it is very common to get a list
of arguments separated by a specific set of characters (whitespace
for example - "split to words"). There are multiple ways reading such
a list, for example shifting it token by token and feed a state machine.
In other cases it's more useful to just have an array with the words and
randomly access elements. P_argv_split() helps with the latter, reading
a list of arguments from a string, splitting at user supplied separator.
Pointer to each element will be stored in the user-allocated string array.
Strings are never copied or allocated - the input string is modified with
\0s.
| call
| level
| summary
|
| P_argv_split
| high
| split string in argv[]/argc array of "words"
|
libporty/util/buf.h
Another common task in network programming is reading a stream and scanning
for full messages (lines in a text stream for example). Problem is that reads
are not atomic, it is possible for a single call to return a full message,
a partial message, multiple messages, or multiple messages ending in a partial
one.
The buf calls provide a call for allocating buffers that can be filled by
such non-atoic messages from a stream and can be queried for full messages
in a FIFO manner.
| call
| level
| summary
|
| P_buf_init
| high
| create a new buffer
|
| P_buf_fill
| high
| fill buffer from string
|
| P_buf_get
| high
| return next full message (or NULL)
|
| P_buf_free
| high
| free message returned by P_buf_get
|
| P_buf_uninit
| high
| destroy buffer, discarding pending messages
|
Internally the buffer is a linked list of messages. The last message
is a partial message (may be even empty). P_buf_fill will start appending
to the tail element of the list until it finds a separator in the input.
At the separator it closes the tail element and allocates/appends a new
one to the list. P_buf_get returns a pointer to the string field of
the first element full element (head of the list) and removes it from
the list. Since this pointer is in the middle of the element allocated
by P_buf_fill, normal free() won't work on it, the user needs to
cal P_buf_free() on this pointer. P_buf_free() will modify the pointer with
the field offset of the string and free the whole element. With this approach
strings are copied from the input only once, and there is only one allocation/free
per message.