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.