batprotocol

batprotocol is a set of libraries in various programming languages to help reading and writing messages of the Batsim protocol. In particular, it enables Batsim clients (typically scheduling algorithms) to serialize messages with a high-level API, and to parse messages coming from Batsim.

User Manual:

• Installation
• Getting started
• Protocol definition
• High-level API reference

Todo

This documentation is under construction. Feel free to contact us if anything is missing or you did not find the information you were looking for.

Architecture

batprotocol strongly relies on FlatBuffers to serialize and deserialize messages. The data structure definitions used by batprotocol are available in the batprotocol.fbs file at the root of the repository.

The data structure definition file is used by the FlatBuffers compiler to generate low-level de/serialization API in various programming languages. This code is made directly available in the batprotocol library for each supported programming language.

In addition to the low-level API, a higher-level API may be provided by batprotocol depending on the programming language. Currently, the C++ implementation provides a higher-level API to write messages, but not to read them.

Design rationale

Here are the criteria that we think are the most important for Batsim simulations and the Batsim protocol

• Portability / Interoperability: Decision-making components should be able to be written in any programming language without modifying Batsim

• Robustness: Malformed messages and invalid decisions should be detected and cause the simulation to fail

• Performance: Simulation is used to reduce time and cost of experimentation. Communication between Batsim and the decision-making component should have small overhead.

• Maintainability: Our manpower is very limited. Our code should not require a lot of regular maintenance work.

We chose to use a serialization library as we think it provides a better tradeoff of the above criteria than doing it ourselves.

FlatBuffers has been chosen as it is maintained, focuses on performance of binary de/serialization, and since its C++ implementation enables to use serialize and deserialize messages in JSON, which is convenient for users in random languages without direct FlatBuffers support and to log, debug and replay Batsim simulations.

Usage

You can give a look at the examples and tests.

• C++: look at the cpp/test directory