[proton-C] An easier and more memory-efficient API for encoding proton messages.

[Alan Conway <ac...@redhat.com>]

Request for comments on this proposed API addition:

Currently encoding a proton message in C requires you to guess at the
size and loop with bigger guesses till you over-allocate.

The proposed API below allows the user to
- encode into an existing buffer if it is big enough.
- re-allocate using alloc/free functions of the users choice if not.
- allocate the *correct* amount of memory for the message.

It serves the simple use case of allocating a new buffer per message:

pn_message_t *msg = ...;
size_t size = 0;
char* buffer = 0;
pn_message_encode_alloc(msg, &buffer, &size, &malloc, &free);

It also serves the more efficient "re-usable expanding buffer" use case
but expands only to the size required by the largest message, rather
than over-allocating by guesswork.

It is easy to use with standard malloc and free but also allows custom
buffer allocation.
/**
�* Encode a pn_message_t as AMQP formatted binary data into *buffer.
�* If the *buffer is NULL or *size is not sufficient, call alloc_fn to
�* allocate sufficient space and free_fn to free the old buffer. Will
�* not allocate more space than is required to encode the message.
�*
�* Updates *buffer and *size to the final buffer location and encoded
�* size of the message. The caller is responsible for freeing the
�* final value of *buffer.
�*
�* @param[in] msg a message object
�* @param[in] buffer the start of the buffer for encoded AMQP data.
�*���If NULL, a buffer will be allocated by calling alloc_fn.
�* @param[in] size the size the initial buffer.
�* @param[out] size the size of the encoded message.
�* @param[in] alloc_fn a function to allocate memory, such as malloc(3)
�* @param[in] free_fn a function to free memory, such as free(3)
�* @return zero on success or an error code on failure
�*/
static int pn_message_encode_alloc(
����pn_message_t *msg, char **buffer, size_t *size,
����void* (*alloc_fn)(size_t), void (*free_fn)(void*));

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org