Exposed APIs

This is written down to address the APIs that makes up the programability archived by using the framework. My thought is that these APIs should be in a event-driven design, without exposing low-level system concepts such as file descriptors... The idea is that this would allow languages to make use of this framework more easily. There are 2 sets of APIs, one in the brokers and one in the subscribers.

On the brokers, the APIs should enable the application to accept a subscriber, and retrieve a buffer to which they can write to and publish. Some considerations:

• The memory managment/registration should be done under the hood (the app gets a ready-to-write-buffer)
• Notifications on when the data is disseminated to all/some subscribers
• Flow-control features

It should probably look like this:

// create a buffer, returns the buffer id
uint32_t create_buffer();

// subscribe a node to a buffer of specific id
// the return value indicates success/failure
int subscribe(int node_id, uint32_t buffer_id);

// get a ready-to-write buffer. 
// the return type `bufferinfo` stores the pointer/size to the buffer as well as other related data. (like buffer id)
// on success it will return an iovec, on failure (because of flow control or whatever), returns null pointer
bufferinfo get_write_buffer(uint32_t buffer_id, size_t size);

// commit a buffer to be disseminated, the size argument must be <= that the one assigned by the framework.
// the ctx argument is to be passed in the callback when the dissemination completes
void commit(bufferinfo vec, size_t size, void* ctx);

// register a callback function to be called when dissemination is complete. 
// the ctx argument in the callback function will be the same as the one passed in commit()
void register_dissemination_cb(function<void(void* ctx)> callback);

On the subscribers, we are interested in when the data arrives.