А вы умеете готовить nested_flatbuffers?
У протокола FlatBuffers имеется интересная возможность — использовать вложенную структуру внутри другой структуры, но хранить ее, как массив сырых данных. Такая оптимизация позволяет уменьшить затраты на память и производительность при чтении/записи данных. Для этого необходимо использовать специальный атрибут — nested_flatbuffers
.
Правда, как это часто водится за разработчиками протоколов, на нормальные примеры сил им уже не хватает. И даже на тематических форумах типа stackoverflow, groups.google и т.п. сложно найти полную информацию — приходится буквально по крупицам собирать все части паззла, чтобы в конце концов понять, как именно написать рабочий код.
В статье я раскрою проблему подробнее и приведу примеры на C, C++ и Rust.
In concept this is very simple: a nested buffer is just a chunk of binary data stored in a ubyte vector, typically with some convenience methods generated to access a stored buffer. In praxis it adds a lot of complexity.
Intro
Во многих проектах часто встречается ситуация, когда необходимо использовать какой-то протокол для передачи данных между компонентами — например, по сети. Конечно, можно использовать самописный вариант, но что если в проекте бэкенд на C, сервер на C++, а фронтенд на JS? Одним языком ограничиться уже не получается, и тогда на помощь могут прийти сторонние библиотеки, например — Protocol Buffers (или Protobuf) и FlatBuffers (FB), обе от Google.
Как это устроено? Программист создает специальный файл со схемой данных, где описывает, какие типы и структуры будут использоваться в качестве сообщений. Затем с помощью отдельного компилятора протокола генерируются файлы на нужном языке. После чего они импортируются в проект: сгенерированный код содержит необходимые типы, структуры и функции (классы и методы), с помощью которых создается сообщение с данными. После чего производится сериализация — это превращение данных в байтовый буффер типа uint8_t*
. Этот буффер можно отправлять куда-нибудь по сети, и на приёмной стороне распаковывать обратно в человекочитаемые данные — это десериализация.
Для справки: у Protobuf схема хранится в файле формата .proto, компилятор — protoc; у FlatBuffers соответственно файлы с расширением .fbs, компилятор flatc.
И хотя FlatBuffers является официально более новым протоколом по сравнению с Protobuf — первый релиз в 2014 году против 2008 года соответственно, — возможности для написания кода как будто бы сильнее ограничены. Например, из-за отсутствия таких, казалось бы, жизненно важных функций, как CopyMessage
, во FlatBuffers приходится долго курить документацию и сгенерированные файлы. С другой стороны FB считается более быстрым в плане сериализации/десериализации, а данные занимают меньше памяти.
Сразу скажу, что я не являюсь экспертом в этой области, хотя у меня был опыт с обоими протоколами. Например, на одной работе я делал визуальный редактор сообщений для Protobuf на wxPython — это были прекрасные человеко-часы дебага и поиска ошибок, потому что вот эта вот динамическая типизация, отсутствие компиляции, рекурсия, рефлексия… всё, как вы любите. Бывшие коллеги кстати говорят, что до сих пор пользуются, успех что ли.
В этой статье я не собираюсь сравнивать плюсы-минусы этих библиотек — за меня это уже сделали другие люди и не один раз: от небольшого обзора до целой научной статьи. Здесь я хочу рассмотреть решение конкретной задачи с использованием FlatBuffers, которая может вам встретиться в проекте: надеюсь, что для кого это окажется полезным.
Problem Setting
Обычно для обмена между компонентами используют сообщения разных типов — например, данные пользователя (имя, уникальный идентификатор, местоположение), значения с датчиков (гироскоп, акселерометр) и так далее. В таком случае сообщения стандартно заключают в объединение union
, которое хранится внутри какого-то основного сообщения:
Файл client.fbs:
namespace my_project.client;
table Request
{
name:string;
}
table Response
{
x:int;
y:int;
z:int;
}
union CommonMessage
{
Request,
Response
}
table Message
{
content:CommonMessage;
}
root_type Message;
Здесь тип Message
является основным для передачи данных. Автоматически сгенерированный код будет храниться в файлах «client_reader.h», «client_builder.h» и «client_verifier.h» для C, для C++ — в «client_generated.h» и т.д.
В чем недостатки такого подхода? Допустим, клиент отправил на сервер сообщение типа Response
, а на сервере его не надо читать — только переслать дальше без изменений. Предположим, что сервер использует собственную схему данных.
Файл server.fbs:
namespace my_project.server;
table Response
{
extra_info: string;
data: my_project.client.Response;
}
Получили сообщение my_project.client.Response
от клиента, хотим добавить к нему какие-то данные и отправить my_project.server.Response
куда-нибудь дальше (например, клиенту на JS). В таком случае придётся собирать это сообщение как-то так (если сервер написан на C++):
void processClientResponse(const my_project::client::Response* msg)
{
flatbuffers::FlatBufferBuilder fbb;
auto clientResponse = my_project::client::CreateResponse(fbb, msg->x(), msg->y(), msg->z());
auto extraInfo = fbb.CreateString("SomeInfo");
auto serverResp = my_project::server::CreateResponse(fbb, extraInfo, clientResponse);
//…
}
Обратили внимание на clientResponse
? Мы пересоздаём заново сообщение, которое только что получили! Причем надо полностью перечислить все поля для копирования из старого в новое. Почему бы просто не написать как-то так: auto clientResponse {*msg}
или вообще использовать msg
напрямую?
Увы, но так хорошо жить API флэтбуфферов нам просто не позволяет.
А тем более на C, откуда там взяться конструктору копирования.
Итак, в чём именно мы здесь проигрываем:
- время выполнения программы — надо сначала прочитать сообщение, а потом запаковать его обратно
- время работы программиста — затраты на написание кода для перегона сообщения из старого в новое. Я здесь рассмотрел простой пример с типом
Response
:, но что если поля сами являются сложными структурами, а их ещё и много — и всё это по новой, да ещё и на другом языке программирования! Бррр, мы разве за этим здесь, в IT? - память — по сути мы храним внутри
Message
специальную структуру данных с какими-то внутренними особенностями, которые могут раздувать размер сообщения
И какой выход?
Attribute nested_flatbuffers
На помощь приходят специальные возможности — можно заменить тип сообщения на массив байтов [ubyte]
и добавить к нему атрибут nested_flatbuffers
указывающий на тип, который раньше соответствовал сообщению… ну почти. Тогда возвращаясь к схеме client.fbs:
union CommonMessage
{
Request,
Response
}
table MessageHolder
{
data: CommonMessage;
}
table Message
{
content: [ubyte](nested_flatbuffer: "MessageHolder");
}
Почему нам понадобился MessageHolder
, и мы не могли обойтись просто CommonMessage
? Дело в том, что nested_flatbuffer
не может иметь тип union, поэтому нужна промежуточная обертка.
Хорошо, у нас теперь есть обновлённое сообщение типа Message
:, но как узнать, что за данные хранятся внутри массива content
?
Для этого можно завести вспомогательный enum Type
, завернуть его в заголовок Header
и добавить как новое поле в типе Message
. Перечисление Type
будет по сути повторять объединение CommonMessage
.
На самом деле промежуточная структура Header
в данном примере необязательна, но в общем случае удобна, если вы захотите добавить что-нибудь ещё.
Файл client.fbs (финальные правки):
// остальная часть схемы без изменений
enum Type:ubyte
{
request,
response
}
table Header
{
type: Type;
}
table Message
{
header: Header;
content: [ubyte](nested_flatbuffer: "MessageHolder");
}
Круто! А как этим пользоваться?
It’s coding time
Наконец мы добрались до практики —, а как именно писать код для сериализации и десериализации данных с помощью нового атрибута? Сразу скажу, что я приведу полные примеры кода без подробных разъяснений, — надеюсь, этого будет достаточно для понимания общей идеи.
Как это делается на C
В C используется особый подход в работе с FB: это не ООП язык, у него даже компилятор другой — flatcc
вместо общего flatc
(и не всем это оказалось удобно). А ещё на C принято использовать специальный макрос для сокращения неймспейса: #define ns(x) FLATBUFFERS_WRAP_NAMESPACE(my_project_client, x)
.
Основывался я на этом примере от разработчиков и на этом от одного из пользователей.
#include "client_builder.h"
#include "client_verifier.h"
#include
int main(int argc, char ** argv)
{
printf("Testing on C\n");
// builder необходим для сериализации: превращения сообщения в байтовый буффер
flatbuffers_builder_t builder;
flatcc_builder_init(&builder);
size_t size = 0;
void* buf;
{
createRequest(&builder);
buf = flatcc_builder_finalize_aligned_buffer(&builder, &size);
receiveBuffer(buf, size);
flatcc_builder_aligned_free(buf);
}
{
flatcc_builder_reset(&builder);
createResponse(&builder);
buf = flatcc_builder_finalize_aligned_buffer(&builder, &size);
receiveBuffer(buf, size);
flatcc_builder_aligned_free(buf);
}
flatcc_builder_clear(&builder);
return 0;
}
void createRequest(flatbuffers_builder_t* builder)
{
ns(Type_enum_t) type = ns(Type_request);
ns(Header_ref_t) header = ns(Header_create(builder, type));
ns(Message_start_as_root(builder));
ns(Message_header_create(builder, type));
ns(Message_content_start_as_root(builder));
flatbuffers_string_ref_t name = flatbuffers_string_create_str(builder, "This is some string for tests!");
ns(Request_ref_t) request = ns(Request_create(builder, name));
ns(CommonMessage_union_ref_t) msg_union = ns(CommonMessage_as_Request(request));
ns(MessageHolder_data_add(builder, msg_union));
ns(Message_content_end_as_root(builder));
ns(Message_end_as_root(builder));
}
void createResponse(flatbuffers_builder_t* builder)
{
ns(Type_enum_t) type = ns(Type_response);
ns(Header_ref_t) header = ns(Header_create(builder, type));
ns(Message_start_as_root(builder));
ns(Message_header_create(builder, type));
ns(Message_content_start_as_root(builder));
ns(Response_ref_t) response = ns(Response_create(builder, 2, 3, 9));
ns(CommonMessage_union_ref_t) msg_union = ns(CommonMessage_as_Response(response));
ns(MessageHolder_data_add(builder, msg_union));
ns(Message_content_end_as_root(builder));
ns(Message_end_as_root(builder));
}
void receiveBuffer(void* buf, size_t size)
{
const int verification_result = ns(Message_verify_as_root(buf, size));
if (flatcc_verify_error_ok != verification_result) {
printf("Unable to verify flatbuffer message\n");
}
ns(Message_table_t) msg = ns(Message_as_root(buf));
ns(Header_table_t) header = ns(Message_header(msg));
ns(Type_enum_t) type = ns(Header_type(header));
printf("Received Type: %u\n", type);
switch(type) {
case ns(Type_request):
processRequest(&msg);
break;
case ns(Type_response):
processResponse(&msg);
break;
default:
printf("Unknown type!\n");
}
}
void processRequest(ns(Message_table_t)* msg)
{
ns(MessageHolder_table_t) content = ns(Message_content_as_root(*msg));
ns(Request_table_t) request = (ns(Request_table_t)) ns(MessageHolder_data(content));
const char* name = ns(Request_name(request));
printf("Result request: %s\n", name);
}
void processResponse(ns(Message_table_t)* msg)
{
ns(MessageHolder_table_t) content = ns(Message_content_as_root(*msg));
ns(Response_table_t) response = (ns(Response_table_t)) ns(MessageHolder_data(content));
int x = ns(Response_x(response));
int y = ns(Response_y(response));
int z = ns(Response_z(response));
printf("Result response: %d.%d.%d\n", x, y, z);
}
В функции receiveBuffer
используется верификация данных, потому что при ошибках могут съехать внутренние смещения и выравнивания данных — это позволит не обрабатывать заведомо сломанный буффер.
Как это делается на C++
#include "flatbuffers/flatbuffers.h"
#include "client_generated.h"
#include "server_generated.h"
#include
namespace cli = my_project::client;
namespace srv = my_project::server;
void createRequest(flatbuffers::FlatBufferBuilder& fbb)
{
auto type = cli::Type::request;
auto header = cli::CreateHeader(fbb, type);
flatbuffers::FlatBufferBuilder fbb2;
auto name = fbb2.CreateString("This is some string for tests!");
auto rq = cli::CreateRequest(fbb2, name);
auto data = cli::CreateMessageHolder(fbb2, cli::CommonMessage::Request, rq.Union());
fbb2.Finish(data);
auto content = fbb.CreateVector(fbb2.GetBufferPointer(), fbb2.GetSize());
auto msg = cli::CreateMessage(fbb, header, content);
cli::FinishMessageBuffer(fbb, msg);
}
void createResponse(flatbuffers::FlatBufferBuilder& fbb)
{
auto type = cli::Type::response;
auto header = cli::CreateHeader(fbb, type);
flatbuffers::FlatBufferBuilder fbb2;
auto rp = cli::CreateResponse(fbb2, 2, 3, 9);
auto data = cli::CreateMessageHolder(fbb2, cli::CommonMessage::Response, rp.Union());
fbb2.Finish(data);
auto content = fbb.CreateVector(fbb2.GetBufferPointer(), fbb2.GetSize());
auto msg = cli::CreateMessage(fbb, header, content);
cli::FinishMessageBuffer(fbb, msg);
}
void receiveBuffer(std::uint8_t* buf, std::size_t size)
{
flatbuffers::Verifier verifier(buf, size);
if (!cli::VerifyMessageBuffer(verifier))
{
std::cerr << "Unable to verify flatbuffer message\n";
return;
}
auto msg = cli::GetMessage(buf);
auto header = msg->header();
auto type = header->type();
std::cout << "Received HeaderType from client: " << static_cast(type) << "\n";
switch (type)
{
case cli::Type::request:
processRequest (msg);
break;
case cli::Type::response:
processResponse(msg);
break;
}
}
void processRequest(const cli::Message* msg)
{
auto content = msg->content_nested_root();
auto rq = content->data_as_Request();
auto name = rq->name();
std::cout << "Result request: " << name->str() <<"\n";
}
void processResponse(const cli::Message* msg)
{
auto content = msg->content_nested_root();
auto rp = content->data_as_Response();
auto x = rp->x();
auto y = rp->y();
auto z = rp->z();
std::cout << "Result response: " << x << "." << y << "." << z <<"\n";
}
Код практически не отличается по смыслу от написанного на C, за исключением того, что построение сообщения производится другим способом — с помощью дополнительного экземпляра fbb2
типа FlatBufferBuilder
для вложенного сообщения. На самом деле разработчики заявляют, что вложенный флэтбуффер можно собирать и так, и так, но в C мне не удалось заставить такую конструкцию работать (а жаль — cо вторым экземпляром билдера код выглядит несколько читабельнее).
Level Up
А теперь самое главное — для чего всё это было нужно? Как именно воспользоваться преимуществом атрибута nested_flatbuffers
?
Рассмотрим вариант, когда C++-сервер использует следующую схему данных:
Файл server.fbs:
include "client.fbs";
namespace my_project.server;
table ClientData
{
extra_info:string;
client_msg:[ubyte](nested_flatbuffer: "my_project.client.MessageHolder");
}
table ServerData
{
server_name:string;
}
union CommonMessage
{
ServerData,
ClientData
}
table Message
{
header: my_project.client.Header;
content: CommonMessage;
}
root_type Message;
Здесь тоже используется сообщение типа Message
, но хранящее просто union со своими собственными типами. Самое главное находится в таблице ClientData
: сообщение с информацией от клиента, которое мы хотим переслать на сервере, содержит «вложенный флэтбуффер» client_msg
— и он должен быть точно такого же типа, что отправил клиент. Под катом продемонстрировано, как правильно его скопировать не распаковывая (комментарии на русском я делал для статьи, на английском — для себя в коде):
// используем глобальный экземпляр для простоты
flatbuffers::FlatBufferBuilder fbb_;
// общий обработчик сообщения, полученного от клиента
void processClientMessage(const cli::Message* msg)
{
fbb_.Clear();
// constructing srv::Message from cli::Message
switch (msg->header()->type())
{
case cli::Type::request:
forwardMessage(msg, "SERVER-REQUEST");
break;
case cli::Type::response:
forwardMessage(msg, "SERVER-RESPONSE");
break;
}
// processing constructed srv::Message to verify it is correct
processServerMessage();
}
// Самая интересная часть – пересылка сообщения от клиента без распаковки деталей
void forwardMessage(const cli::Message* msg, const char* extra_info_str)
{
// Yes, we should recreate header as FlatBuffers don't have API to just copy it from msg->header()
auto header = cli::CreateHeader(fbb_, msg->header()->type());
auto extra_info = fbb_.CreateString(extra_info_str);
// The main part: copying nested buffer from client to server message
auto client_msg = msg->content();
auto client_msg_vec = fbb_.CreateVector(client_msg->Data(), client_msg->size());
auto content = srv::CreateClientData(fbb_, extra_info, client_msg_vec);
auto server_msg = srv::CreateMessage(fbb_, header, srv::CommonMessage::ClientData, content.Union());
srv::FinishMessageBuffer(fbb_, server_msg);
}
// пример обработки сообщения, сгенерированного сервером
void processServerMessage() const
{
std::uint8_t* buf = fbb_.GetBufferPointer();
auto msg = srv::GetMessage(buf);
auto header = msg->header();
auto header_type = header->type();
auto content_type = msg->content_type();
std::cout << "Received HeaderType from server: " << static_cast(header_type) << "\n";
std::cout << "Received ContentType from server: " << static_cast(content_type) << "\n";
if (content_type != srv::CommonMessage::ClientData)
{
std::cerr << "Not implemented Handler for this content_type\n";
return;
}
// process only ClientData for demonstration purposes
auto content = msg->content_as_ClientData();
auto extra_info = content->extra_info();
auto client_msg = content->client_msg_nested_root();
std::cout << "Result request from server: extra_info: " << extra_info->str() << "\n";
switch(header_type)
{
case cli::Type::request:
{
auto client_rq = client_msg->data_as_Request();
auto client_name = client_rq->name();
std::cout << "- client_msg: " << client_name->str() << "\n";
break;
}
case cli::Type::response:
{
auto client_rp = client_msg->data_as_Response();
auto x = client_rp->x();
auto y = client_rp->y();
auto z = client_rp->z();
std::cout << "- client_msg: " << x << "." << y << "." << z << "\n";
break;
}
}
}
Отдельно ещё раз хочу сделать акцент на копировании:
auto client_msg = msg->content();
auto client_msg_vec = fbb_.CreateVector(client_msg->Data(), client_msg->size());
И всё! Не надо знать деталей, что именно к нам пришло в msg->content()
— мы просто берём и копируем сырой буффер как есть.
Красиво и удобно.
Bonus
Так случилось, что у меня для вас есть ещё и полноценный пример на Rust. Согласен, внезапно, но почему бы и нет. Сейчас язык набирает обороты, и уже всё чаще случается, что им заменяют C++. Наконец-то, теперь мы будем спасены! Короче говоря, who knows
extern crate flatbuffers;
#[allow(dead_code, unused_imports, non_snake_case)]
#[path = "../../fbs/client_generated.rs"]
mod client_generated;
pub use client_generated::my_project::client::{
get_root_as_message,
Type,
Request,
Response,
Header,
CommonMessage,
MessageHolder,
Message,
RequestArgs,
ResponseArgs,
HeaderArgs,
MessageHolderArgs,
MessageArgs};
fn create_request(mut builder: &mut flatbuffers::FlatBufferBuilder)
{
// в Rust слово type является ключевым, поэтому генератор автоматически добавляет _
let type_ = Type::request;
let header = Header::create(&mut builder, &mut HeaderArgs{type_});
let data_builder = {
let mut b = flatbuffers::FlatBufferBuilder::new();
let name = b.create_string("This is some string for tests!");
let rq = Request::create(&mut b, &RequestArgs{name: Some(name)});
let data = MessageHolder::create(&mut b, &MessageHolderArgs{
data_type: CommonMessage::Request,
data: Some(rq.as_union_value())});
b.finish(data, None);
b
};
let content = builder.create_vector(data_builder.finished_data());
let msg = Message::create(&mut builder, &MessageArgs{
header: Some(header),
content: Some(content)});
builder.finish(msg, None);
}
fn create_response(mut builder: &mut flatbuffers::FlatBufferBuilder)
{
let type_ = Type::response;
let header = Header::create(&mut builder, &mut HeaderArgs{type_});
let data_builder = {
let mut b = flatbuffers::FlatBufferBuilder::new();
let rp = Response::create(&mut b, &ResponseArgs{x: 2, y: 3, z: 9});
let data = MessageHolder::create(&mut b, &MessageHolderArgs{
data_type: CommonMessage::Response,
data: Some(rp.as_union_value())});
b.finish(data, None);
b
};
let content = builder.create_vector(data_builder.finished_data());
let msg = Message::create(&mut builder, &MessageArgs{
header: Some(header),
content: Some(content)});
builder.finish(msg, None);
}
fn process_request(msg: &Message)
{
let content = msg.content_nested_flatbuffer().unwrap();
let rq = content.data_as_request().unwrap();
let name = rq.name().unwrap();
println!("Result request: {:?}", name);
}
fn process_response(msg: &Message)
{
let content = msg.content_nested_flatbuffer().unwrap();
let rp = content.data_as_response().unwrap();
println!("Result response: {}.{}.{}", rp.x(), rp.y(), rp.z());
}
fn receive_buffer(buf: &[u8])
{
// NOTE: no verification exists in Rust yet
let msg = get_root_as_message(buf);
let header = msg.header().unwrap();
let type_ = header.type_();
println!("Received Type: {:?}", type_);
match type_ {
Type::request => {
process_request(&msg);
}
Type::response => {
process_response(&msg);
}
}
}
fn main() {
println!("Testing on Rust");
let mut builder = flatbuffers::FlatBufferBuilder::new_with_capacity(1024);
{
create_request(&mut builder);
let buf = builder.finished_data();
receive_buffer(&buf);
}
{
builder.reset();
create_response(&mut builder);
let buf = builder.finished_data();
receive_buffer(&buf);
}
}
FIN
Атрибут nested_flatbuffers
является очень полезным и удобным способом для оптимизации передачи данных при использовании протокола FlatBuffers. Другое дело, что не так просто понять сходу, как именно его применять.
Вообще документация и примеры от разработчиков тех или иных протоколов иногда оставляют желать лучшего. Синтаксис таких библиотек является довольно специфичным, и по сути на его понимание приходится часто тратить не меньше времени и сил, чем на изучение просто нового языка программирования. Особенно часто это случается, когда упоминаются какие-то редкие возможности.
nested_flatbuffers
обстоит дело с использованием собственных аллокаторов в C: «Да, юзеры, вы можете использовать свои аллокаторы аж двумя (2!) разными способами, но примеров мы вам, конечно, не дадим. А зачем?! Курите исходники» *звуки trolololo Так что если вы вдруг озадачитесь такой же проблемой, то наверняка наткнётесь на моё обсуждение с разработчиками на одном из форумов, — жаль только, что их ответ был крайне развёрнутый, но почти бесполезный.
Поэтому хочется просто пожелать вам поменьше сталкиваться с такими неприятностями, а ещё иногда не жалеть время на написание доков для других программистов — мы же ведь коллеги по цеху, да?