FlatBuffers要点

​ ​FlatBuffers发布出来一周多，周末便抽时间先研究下它的使用方法。Flatbuffers的idl的语法主要参考[http://google.github.io/flatbuffers/md__schemas.html ]。本文主要介绍几个它的monster.fbs没有给出说明的几个语法点和相关的注意事项。

1 comment

它的注释中介绍了”///“，说明是可以生成document comment. 我写了如下fbs代码(假设文件名称还是monster.fbs)：

       /// struct Vec3 {
   ///   x:float;
   ///   y:float；
   ///   z:float;
   /// }

“flatc -c monster.fbs"命令编译后，生成代码为：

<!-- lang: cpp -->
/// struct Vec3 {   x:float;   y:float;   z:float; }

2 struct

struct默认的aliagnment是4Byte.
如下fbs代码(假设文件名称还是monster.fbs)：

struct Vec4  {
  x : float;
  y : short;
  z : float;
  w : short;
}

“flatc -c monster.fbs"命令编译后，生成代码为：

MANUALLY_ALIGNED_STRUCT(4) Vec4 {
 private:
  float x_;
  int16_t y_;
  int16_t __padding0;
  float z_;
  int16_t w_;
  int16_t __padding1;

 public:
  Vec4(float x, int16_t y, float z, int16_t w)
    : x_(flatbuffers::EndianScalar(x)), y_(flatbuffers::EndianScalar(y)), __padding0(0), z_(flatbuffers::EndianScalar(z)), w_(flatbuffers::EndianScalar(w)), __padding1(0) {}
  float x() const { return flatbuffers::EndianScalar(x_); }
  int16_t y() const { return flatbuffers::EndianScalar(y_); }
  float z() const { return flatbuffers::EndianScalar(z_); }
  int16_t w() const { return flatbuffers::EndianScalar(w_); }
};
STRUCT_END(Vec4, 16);

3 original_order

FB（FlatBuffers的简称，下同）用original_order来保持fbs中table的field顺序，FB说明中说明它是用来修饰table的（”original_order (on a table)“），其实他也可以修饰struct。

如下fbs代码(假设文件名称还是monster.fbs)：

struct Vec4_ (original_order) {
  x : float;
  y : short;
  z : float;
  w : short;
}

“flatc -c monster.fbs"命令编译后，生成代码为：

STRUCT_END(Vec4, 16);
MANUALLY_ALIGNED_STRUCT(4) Vec4_ {
 private:
  float x_;
  int16_t y_;
  int16_t __padding0;
  float z_;
  int16_t w_;
  int16_t __padding1;

 public:
  Vec4_(float x, int16_t y, float z, int16_t w)
    : x_(flatbuffers::EndianScalar(x)), y_(flatbuffers::EndianScalar(y)), __padding0(0), z_(flatbuffers::EndianScalar(z)), w_(flatbuffers::EndianScalar(w)), __padding1(0) {}

  float x() const { return flatbuffers::EndianScalar(x_); }
  int16_t y() const { return flatbuffers::EndianScalar(y_); }
  float z() const { return flatbuffers::EndianScalar(z_); }
  int16_t w() const { return flatbuffers::EndianScalar(w_); }
};
STRUCT_END(Vec4_, 16);

4 force_align

force_align这个关键字用来对struct进行align，此处我想说明FB的一个bug。
如下fbs代码(假设文件名称还是monster.fbs)：

struct Vec3 (force_align : 8 ) {
  x : float;
  y : float;
  z : float;
}

“flatc -c monster.fbs"命令编译后，生成代码为：

MANUALLY_ALIGNED_STRUCT(8) Vec3 {
 private:
  float x_;
  float y_;
  float z_;

 public:
  Vec3(float x, float y, float z)
    : x_(flatbuffers::EndianScalar(x)), y_(flatbuffers::EndianScalar(y)), z_(flatbuffers::EndianScalar(z)) {}

  float x() const { return flatbuffers::EndianScalar(x_); }
  float y() const { return flatbuffers::EndianScalar(y_); }
  float z() const { return flatbuffers::EndianScalar(z_); }
};
STRUCT_END(Vec3, 12);

请注意上面最后一行代码的最后一个参数"12”，我已经说明以8Byte作为alignment，但是它给出的struct Vec3的size仍然为12，如果你使用上面的代码，g++会给出这样的错误提示"error: static assertion failed: compiler breaks packing rules”。

解决方法有三个，第一，你把这行代码注释掉。or 第二，把数字“12”手工改成“16”。or 第三，等待官方修正这个bug（我已经提交了这个bug:https://github.com/google/flatbuffers/issues/18）。

补充：bug已经由gwvo(https://github.com/gwvo)修正了。修正链接见（https://github.com/AlexStocks/flatbuffers/commit/65cfa18855abc712faa1bf0cb5c3b88ab8df4b28）

之所以Vec3的size没有计算正确，原因是作者分析完struct的各个成员后忘了这个语法特性了。我下面稍微补充下FB的编译器出现这个bug的原因。

bug修改之前，void Parser::ParseDecl() 一块代码如下：

// 验证struct的开头为 "{"
Expect('{');    
// 分析struct的每一行(field)，其主功能是为struct添加member并增加struct的bytesize            
while (token_ != '}') ParseField(struct_def);  
// 为struct添加padding成员以进行alignment，然后计算struct的bytesize值
// 注意：作者忘了"force_align"这个关键语法特性就计算struct的bytesize     
struct_def.PadLastField(struct_def.minalign);   
// 验证struct的结尾为 "}"                                                                      
Expect('}'); 
// 此时才开始查找"force_align"这个keyword             
auto force_align = struct_def.attributes.Lookup("force_align");  
if (fixed && force_align) {
  auto align = static_cast<size_t>(atoi(force_align->constant.c_str()));
// 虽然计算出了struct应该以align为基准进行alignment，但是为时已晚，无法改变struct的bytesize了
  struct_def.minalign = align;                                                           
}

通过上面分析，就可以晓得问题所在，修正后的代码为：

Expect('{');
while (token_ != '}') ParseField(struct_def);
auto force_align = struct_def.attributes.Lookup("force_align");
if (fixed && force_align) {
  auto align = static_cast<size_t>(atoi(force_align->constant.c_str()));
  struct_def.minalign = align;
}
struct_def.PadLastField(struct_def.minalign);   // !!!
Expect('}');                                    // !!!
}

注意上面的代码块，仅仅是对”!!!“标识的两行代码在代码块中往下移动了几行，就可以正确计算struct的bytesize了。再次感谢gwvo的工作。

5 struct&table

table 是FB实现向前\向后兼容的关键。table每个field默认都是optional的，而struct的每个成员是required的。把idl转换为C++ or Java语言时候，FB不会修改struct成员的顺序（如果struct的成员无法alignment FB会自动添加padding成员），但是会改变table成员的顺序以使得它占用最小的内存空间。所以，table 提供向前\向后兼容特性，而你一旦定义一个struct后，你就无法再添加新的member。

table的每个对象被序列化后的内存空间中都存在着一个额外(除却数据内存空间外)的辅助空间以说明其内存对象分布，称之为vtable。通过vtable我们可以知道这个table对象有哪些成员。如果同一个table的不同对象被序列化进同一个内存空间内，那么只有第一个对象存储了vtable的详细数据，而其他对象的vtable区域只存储一个指向第一个对象的vtable的指针即可。因为table对象需要vtable以说明自己，所以对他它序列化后占用的内存空间一般都比序列化一个struct对象后占用的内存空间大。

vtable的每个元素占用2Bytes。它的第一个element是vtable的elements总数目（包含第一个element自身），第二个是对象的以字节为单位的内存大小（包含vtable占用的内存空间大小），后面的element就是table各个成员在object区域的伪指针(即偏移大小)。如果table有N个member，则vtable大小就是((N + 2) * 2) Bytes.

FB的对象区域每个成员基本上都是len+value形式。vtable内则是type id + offset形式。offset可以理解为一个伪指针，通过它可以找到每个成员。FB对每个成员进行赋值之前，要先进性alignment，然后把value转换为endian形式，FB保证这些值在不同平台上都有效。

反序列化一个对象后，访问一个对象的某个成员时，如果其序列化后的空间内没有这个成员的数据，那么就返回其默认值。同理，序列化一个对象时，如果这个对象的成员的值与默认值相等，则不会把这个值序列化进内场空间。如果一个table的field都用默认值，那么此时对它序列化后占用的内存空间要比序列化一个struct对象后占用的内存空间小。

FB还有一个类型union，它的文档里面提到"FlatBuffers can of course be wrapped inside other containers where needed, or you can use its union feature to dynamically identify multiple possible sub-objects stored. Additionally, it can be used together with the schema parser if full reflective capabilities are desired.“。我理解不多，有待后面分析。

6 summary

FB的document里面提到开发它的缘由。
“在过去的好日子里，说到提高性能就是开发更高效的CPU指令和提供更短的CPU计算周期，但现在那个好日子一去不复返了，因为回首回望，我们发现CPU已经发展太快而把他的小弟内存拉下了好几圈了。现在提高性能的战场应该是在内存而非CPU了。快速高效的方法应该是：一个对象在内存中如何高效的占用尽可能少的空间，如何更快速的访问它，以及怎么为它分配这些空间和如何拷贝它。”
“进程一个重要的是任务就是对它的数据进行序列化，这可能要使用很多临时的变量以分析和暂时存储这些数据，也可能使用不甚高效的内存分配策略。而FB可以做到不使用临时对象、没有额外的内存分配、不拷贝和让对象占用尽可能少的内存空间。除了做到这些，FB能保证数据本身的向前\向后兼容性、跨平台特性。另外，它以小端数据格式作为标准数据格式”
“FB主要关注移动开发平台(这个平台与PC平台相比就如同上世界把PC与大型机相比一样，它的内存空间大小和数据传输速度都稍显紧缺)，它尤其关注一类移动应用：games”
根据我对FB源码的研究，诚哉斯言！