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
In order to receive events, the handle must have been opened for reading using one of
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.