int gre_io_receive(
gre_io_t * handle,
gre_io_serialized_data_t ** buffer
)
Receive a serialized event from a channel. By default this call blocks
until an event is received or until the channel is destroyed unless the
GRE_IO_FLAG_NONBLOCK flag was passed to the
gre_io_open()call.
In order to receive events, the handle must have been opened for reading
using one of GRE_IO_RDONLY or
GRE_IO_XRDONLY.
Parameters:
handle A valid handle created with gre_io_open()
buffer A pointer to a serialized buffer pointer. If the buffer is NULL then a new
buffer is allocated otherwise the buffer provided is used to store the received event.
Returns:
The size of the message received in bytes or -1 on failure.
When a data buffer is successfully received, the event specific content can be extracted by
making a call to gre_io_unserialize. The values returned by the unserialize call
will be pointers directly into the memory allocated to the data buffer. Clients can read and
write to the extracted values (such as event name, event format and data payload) directly
as long as the serialized buffer is not re-used at the same time. Any data from the event
that needs to be maintained across calls to gre_io_receive must be copied by
the user before the serialized buffer is re-used.