Inspirel banner

Programming Distributed Systems with YAMI4

6.3.2 C++

The following example is an extract from the calculator server that accepts the message from the client and computes the sum and difference of two numbers provided in the message payload. The message handler needs to be registered in the server-side agent so that incoming messages can be properly routed to it.

void call(incoming_message & im)
{
    const parameters & params = im.get_parameters();

    const int a = params.get_integer("a");
    const int b = params.get_integer("b");

    parameters reply_params;

    reply_params.set_integer("sum", a + b);
    reply_params.set_integer("difference", a - b);

    im.reply(reply_params);
}

In the above example the call() function is a callback implementation that is invoked by the agent whenever there is an incoming message addressed to the logical object for which the handler was registered. The callback can be implemented as any callable entity.

The im parameter of this operation is an object that refers to internal agent's structures and that allows to initiate further communication that is needed to send the reply or rejection to the originating client program. Several operations can be executed on this message object and in this example the parameters object that was received as part of this message's payload is inspected with the get_parameters() function. Later, the reply is prepared based on the incoming parameters - in this example the server reads two values and computes their sum and difference and inserts both result values into a single parameters object that becomes the reply payload. After the reply() function is called on the incoming message object, the processing is completed and the agent can proceed with transmission of the reply to the client.

The above pattern is the most fundamental idiom for server-side processing of incoming messages and can be characterized by the fact that the complete message processing is contained in the scope of the callback invocation.

It is also possible to move the state of incoming message to another freshly created incoming message instance with the help of the moving constructor. This allows the server to process the incoming message asynchronously and outside of the handler callback.