Figure 1: Diagram of a GEP protocol-based client/server.
GEP-based protocols are asynchronous by definition: The sender sends
a protobuf message to the receiver, and it does not wait for an answer
from the receiver. If your protocol needs status/return messages,
they need be implemented on top of GEP.
The asynchronous behavior is coherent with the operation of the main user,
where one server sends and receives messages to/from multiple clients.
The use of protobuf messages allows both clients and servers that keep
their data structures as protobufs themselves. This makes the code
extremely simple, and very easy to serialize (e.g. dump state in the
logs in a systematic way).
GEP Manual
----------
The best way to learn how to use GEP is by checking the provided example,
called SGP. Check the [SGP Documentation](example). Note that
all the `example/sgp_*` files are mostly boilerplate, so it should be
easy to adapt them for your own protocol.
Note that both the client and server stub classes, when started, will
create a thread in charge of receiving messages and running the callback
functions.
In order to test the current code, you need a modern version of protobuf
(This will change once proto3 is officially released).
The following code installs it in a private, temporary directory.
```bash
git clone https://github.com/google/protobuf
cd protobuf/
./autogen.sh
PROTOBUF_PREFIX=/tmp/usr
./configure --prefix=$PROTOBUF_PREFIX
make
make install
cd ..
```
Once you have installed it, try the libgep code:
```bash
git clone https://github.com/google/libgep
cd libgep/
PROTOBUF_PREFIX=/tmp/usr make
PROTOBUF_PREFIX=/tmp/usr make test
```
`make` will create 4 libraries, namely `libgepclient.a`,
`libgepclient-lite.a`, `libgepserver.a`, and
`libgepserver-lite.a`. You also need the .h headers in
the `include/` directory.
GEP Operation: Protocol Definition
----------------------------------
As mentioned before, a GEP-based protocol is defined by 2 sets of
protobuf messages (those that clients can send to the server, and
those that the server can send to the clients), a port number,
and the per-protobuf message tags.
In the future most of this information can be provided by the user
using something like a
[grpc](http://www.grpc.io/) service, but currently the user needs
to define this information in her own C++ class.
The first part is to define the set of messages that clients and
server can exchange to each other:
$ cat examples/sgp.proto
...
message Command1 {
optional int64 a = 1;
optional int32 b = 2;
}
message Command2 {
optional int64 id = 1;
}
...
Figure 2: SGP (a GEP-based protocol) messages.
Then, the user must define the protocol as a class (called SGPProtocol
in this case) that derives from GepProtocol, and which implements a
couple of functions that map a set of unique IDs (aka ``tags'') to
the protobuf messages that can be passed back and forth between client
and server.
In particular, GetTag() maps a protobuf message to a tag, while
GetMessage() maps a tag to a protobuf message.
$ cat example/sgp_protocol.h
...
class SGPProtocol : public GepProtocol {
...
// supported messages
static constexpr uint32_t MSG_TAG_COMMAND_1 =
MakeTag('c', 'm', 'd', '1');
static constexpr uint32_t MSG_TAG_COMMAND_2 =
MakeTag('c', 'm', 'd', '2');
...
// returns the tag associated to a message.
virtual uint32_t GetTag(const GepProtobufMessage *msg);
// constructs an object of a given type.
virtual GepProtobufMessage *GetMessage(uint32_t tag);
};
...
$ cat example/sgp_protocol.cc
uint32_t SGPProtocol::GetTag(const GepProtobufMessage *msg) {
if (dynamic_cast