void vortex_channel_set_serialize ( VortexChannel channel,
axl_bool  serialize 
)

Allows to serialize all messages/replies (MSG, ERR, RPY, ANS/NUL) received on a particular channel, by checking that previous messages/replies were delivered, avoiding thread race conditions.

This function allows to ensure that all calls to the frame received handler (VortexOnFrameReceived) are done in a way they are ordered. By calling to this function, the vortex engine will ensure that all frames received will be serialized without taking into consideration the thread planner.

FUNCTION BACKGROUND: why?

Though all frames received are ordered, once they are processed by the vortex reader, they are passed in to the second level handler (for the frame received activation) by using threads.

Beyond this point, the thread planner could decide to stop a thread that carries the RPY 1, and give priority to the thread carrying the RPY 2, causing that the frame receiver to process the frame RPY 2 before its preceding.

In most cases this is not a problem because all replies are matched with its corresponding MSG, but under some circumstances where replies have a relation, like chunks of a file transferred, it is really required to process chunks received in an strict order.

CONFIGURING LISTENER SIDE:

Because the function enforces ordered delivery without considering how the thread planner will do, the function must be called at the side where it is required. If serial behaviour if required at the listener side, then a call on this side is required. The same applies to the initiator/client side.

In the case you want ordered delivery at the listener side, you must configure the channel before receiving any message/reply. To do so, configure a start channel handler (VortexOnStartChannel or VortexOnStartChannelExtended), and get access to the channel being accepted by using vortex_connection_get_channel, by providing the channel_num received:

1 axl_bool my_start_channel (int channel_num,
2  VortexConnection * connection,
3  axlPointer user_data)
4 {
5  // get channel reference
6  VortexChannel * channel = vortex_connection_get_channel (connection, channel_num);
7 
8  // configure serialize behaviour
9  vortex_channel_set_serialize (channel, axl_true);
10 
11  // accept channel
12  return axl_true;
13 }
Parameters
channelThe channel to make frame received handler to behave in a serialize fashion.
serializeaxl_true to enable serialize, axl_false if not.

References vortex_mutex_lock(), and vortex_mutex_unlock().