Describes the data modes used for delivering data from the server to the client. More...
Describes the data modes used for delivering data from the server to the client.
The server may send data to the client in one of two modes: PUSH and PULL. The current data mode is changed using the playerc_client_datamode function.
The default mode for clients is PULL.
PUSH Mode
PUSH mode is more reliable for ensuring that all data generated by the server will reach the client, although there is still a risk of message queues overflowing in this mode.
When in PUSH mode the server will send all messages directed at the client as soon as they become available. For example, if a message carrying range readings from a laser scanner is generated by a laser data, it will be added to the client's queue and sent out as soon as possible by the server. When a client read is performed by calling playerc_client_read the next packet in the client's queue is read.
When using PUSH mode be aware that the client must keep up with the speed of generation of DATA messages by the server. If the client cannot read messages as fast as the server is producing them, the data received by the client will become increasingly out of date. This may be avoidable by setting appropriate add-replace rules, but read the next paragraph first.
If you are using the TCP protocol for the connection between the client and the server, and are in PUSH mode, then add-replace rules for the client's queue may not function correctly. This is because messages will leave the client's queue on the server as soon as there is space for them in the operating system's TCP buffer for the connection. As a result, messages will not be in the actual queue long enough for add-replace rules to function correctly until this buffer becomes full (it is typically many megabytes large). To avoid this problem, use PULL mode.
PULL Mode
PULL mode is the preferred mode for most clients. When used together with suitable add-replace rules, it guarentees that data received by the client is the most up-to-date data available from the server at the beginning of the read function.
When in PULL mode the server will send all messages directed at the client, but only when requested by the client. This request is performed at the beginning of every call to playerc_client_read, so client programs do not need to perform it themselves. The client will then read all data that is waiting on the server in one go. In this mode, client programs do not need to continually call read until there are no messages waiting.
When using PULL mode, beware of the client's queue on the server overflowing, particularly if using TCP. While PUSH mode can take advantage of the OS's TCP buffer, in PULL mode this buffer is not used until the client requests data. The standard length of the client's message queue on the server is 32 messages. To avoid the queue overflowing, use add-replace rules to automatically replace older messages with more up-to-date messages for the same message signature.
Data Mode Example
The following code will change a client's data mode to PULL mode and set an add-replace rule to replace all DATA messages generated by the server, preventing the message queue from overflowing when they are produced faster than the client reads and ensuring that the client receives the most up-to-date data.
if (playerc_client_datamode (client, PLAYERC_DATAMODE_PULL) != 0)
{
fprintf(stderr, "error: %s\n", playerc_error_str());
return -1;
}
if (playerc_client_set_replace_rule (client, -1, -1, PLAYER_MSGTYPE_DATA, -1, 1) != 0)
{
fprintf(stderr, "error: %s\n", playerc_error_str());
return -1;
}
The add-replace rule specifies that any message of type PLAYER_MSGTYPE_DATA will be replaced by newer versions. So, if a driver produces a data packet and there is already a data packet from that driver with the same signature on the queue, it will be removed from the queue (and not sent to the client), with the new packet pushed onto the end of the queue.