Embedding libose

Table of Contents

• libose does not allocate
• Size the buffer for the overhead
• Reading the size
• Where to go next

how to get a bundle, and what libose expects of you

Building and Configuration covers compiling the library. This page covers the part that comes before any of the API is useful: getting a bundle to work with, and the one contract libose asks of the host.

libose does not allocate

The host allocates the memory, and libose never asks for more. There is no allocator to hook, and a bundle cannot grow past the buffer it was given. That is deliberate: it is what makes the library usable on a microcontroller and inside an audio callback, where allocation is either unavailable or forbidden.

A bundle is created from memory you already own:

char *bytes = (char *)malloc(4096);
ose_bundle bundle = ose_newBundleFromCBytes(4096, bytes);

Static or stack memory works equally well, and is what the examples use.

ose_bundle is opaque. It may be a pointer, or a struct wrapping one – it is a struct when OSE_CONF_DEBUG is defined and a bare pointer otherwise, which is worth knowing because objects compiled with and without that flag cannot be linked together.

Size the buffer for the overhead

A bundle is not the only thing in that memory. libose writes a context around it – sizes, a status word for errno, a lookup cache – and that costs a fixed number of bytes before any of your data fits.

OSE_CONTEXT_MAX_OVERHEAD is that number. As of this writing it is 2056 bytes. If you need room for 32 bytes of your own, ask for both:

const int32_t n = OSE_CONTEXT_MAX_OVERHEAD + 32;
char *bytes = (char *)malloc(n);
ose_bundle bundle = ose_newBundleFromCBytes(n, bytes);

Warning

A buffer smaller than OSE_CONTEXT_MAX_OVERHEAD does not fail loudly. ose_newBundleFromCBytes asserts the size, and asserts are compiled out of release builds, so what you get instead is a bundle that initialises, reports a size, accepts calls, and silently holds nothing: every push is declined because there is no room. If pushes appear to do nothing, check this first. Measured: a 2048-byte buffer yields a bundle whose size never moves off 16.

Reading the size

ose_readSize gives the number of bytes currently used:

int32_t size = ose_readSize(bundle);

The same value lives four bytes behind the bundle pointer, which is occasionally useful in a debugger:

int32_t size = ose_readInt32(bundle, -4);

Both report 16 for a fresh bundle – the length of the OSC bundle header – and both grow as elements are added.

Where to go next

• The Bundle as a Stack – the model everything else is built on
• Example: Create a Bundle – a complete program that builds one message
• Example: Simple OSC Server – receiving OSC and responding to it
• OSE Virtual Machine – the virtual machine, if you want more than a bundle