【C++】Google Protocol Buffer（protobuf）详解（二）

代码走读：caffe中protobuf的详细使用过程

【一】proto文件，以caffe.proto中BlobShape为例

syntax = "proto2";	//指明protobuf版本，默认是v2，其它版本："proto3"package caffe; 	// 最终生成c++代码： namespace caffe message BlobShape {	// 最终生成c++代码： class BlobShape : public ::google::protobuf::Message {//下面语句最终生成c++代码： google::protobuf::RepeatedField< ::google::protobuf::int64 > dim_;repeated int64 dim = 1 [packed = true];	//repeated列表字段，等号后面数字表示标识符，[packed=true]保证更高效的编码
}

【二】编译命令 protoc -I=. --cpp_out=. caffe.proto

【三】生成的caffe.pb.h

......
namespace caffe {	//对应caffe.proto中 package caffe;
// protobuf内部实现细节——不要调用这些接口
void  protobuf_AddDesc_caffe_2eproto();
void protobuf_AssignDesc_caffe_2eproto();
void protobuf_ShutdownFile_caffe_2eproto();class BlobShape;
// ===================================================================
class BlobShape : public ::google::protobuf::Message {	//对应caffe.proto中 message BlobShapepublic:BlobShape(); // 构造函数virtual ~BlobShape(); //析构函数BlobShape(const BlobShape& from); // 拷贝构造函数inline BlobShape& operator=(const BlobShape& from) { //赋值构造函数CopyFrom(from);return *this;}// ** UnknownFieldSet用于跟踪解析协议消息但其字段编号或类型无法识别时看到的字段。
// 这种情况最常发生在将新字段添加到消息类型中，然后包含这些字段的消息由添加新类型之前编译的旧软件读取。
// 大多数用户永远不需要使用这个类。比如在caffe中就没有使用到
// 参考网址：https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/UnknownFieldSetinline const ::google::protobuf::UnknownFieldSet& unknown_fields() const {return _unknown_fields_;}inline ::google::protobuf::UnknownFieldSet* mutable_unknown_fields() {return &_unknown_fields_;}// ** 描述元数据，主要用在反射上，caffe中没有用到
// 参考网址：http://www.blogjava.net/DLevin/archive/2015/04/01/424012.htmlstatic const ::google::protobuf::Descriptor* descriptor();static const BlobShape& default_instance();void Swap(BlobShape* other);	// 交换// implements Message 消息实现----------------------------------------------BlobShape* New() const;	// 新建void CopyFrom(const ::google::protobuf::Message& from);	// 复制void MergeFrom(const ::google::protobuf::Message& from);	// 合并：单数字段会被覆盖、Repeated (类似链表)字段会被连接到一起void CopyFrom(const BlobShape& from);void MergeFrom(const BlobShape& from);void Clear();	// 清除消息的所有字段，并将它们设置为默认值。bool IsInitialized() const;	// 快速检查是否所有必需字段都设置了值。int ByteSize() const;	// 消息的序列化大小bool MergePartialFromCodedStream(::google::protobuf::io::CodedInputStream* input);	//从流中读取协议缓冲区并将其合并到此消息中。void SerializeWithCachedSizes(::google::protobuf::io::CodedOutputStream* output) const;	//序列化消息而不重新计算大小。::google::protobuf::uint8* SerializeWithCachedSizesToArray(::google::protobuf::uint8* output) const;	//序列化到output中int GetCachedSize() const { return _cached_size_; }	//返回上次调用ByteSize()的结果private:void SharedCtor();void SharedDtor();void SetCachedSize(int size) const;public:::google::protobuf::Metadata GetMetadata() const;	// 获取缓冲大小// nested types message内嵌的类型 ----------------------------------------------------// 如果在proto的mesage中定义/* enum SnapshotFormat {HDF5 = 0;BINARYPROTO = 1;}*/// 则生成如下代码：/*enum SolverParameter_SnapshotFormat {SolverParameter_SnapshotFormat_HDF5 = 0,SolverParameter_SnapshotFormat_BINARYPROTO = 1};bool SolverParameter_SnapshotFormat_IsValid(int value);const SolverParameter_SnapshotFormat SolverParameter_SnapshotFormat_SnapshotFormat_MIN = SolverParameter_SnapshotFormat_HDF5;const SolverParameter_SnapshotFormat SolverParameter_SnapshotFormat_SnapshotFormat_MAX = SolverParameter_SnapshotFormat_BINARYPROTO;const int SolverParameter_SnapshotFormat_SnapshotFormat_ARRAYSIZE = SolverParameter_SnapshotFormat_SnapshotFormat_MAX + 1;typedef SolverParameter_SnapshotFormat SnapshotFormat;static const SnapshotFormat HDF5 = SolverParameter_SnapshotFormat_HDF5;static const SnapshotFormat BINARYPROTO = SolverParameter_SnapshotFormat_BINARYPROTO;static inline bool SnapshotFormat_IsValid(int value) {return SolverParameter_SnapshotFormat_IsValid(value);}static const SnapshotFormat SnapshotFormat_MIN = SolverParameter_SnapshotFormat_SnapshotFormat_MIN;static const SnapshotFormat SnapshotFormat_MAX = SolverParameter_SnapshotFormat_SnapshotFormat_MAX;static const int SnapshotFormat_ARRAYSIZE = SolverParameter_SnapshotFormat_SnapshotFormat_ARRAYSIZE;static inline const ::google::protobuf::EnumDescriptor*SnapshotFormat_descriptor() {return SolverParameter_SnapshotFormat_descriptor();}static inline const ::std::string& SnapshotFormat_Name(SnapshotFormat value) {return SolverParameter_SnapshotFormat_Name(value);}static inline bool SnapshotFormat_Parse(const ::std::string& name, SnapshotFormat* value) {return SolverParameter_SnapshotFormat_Parse(name, value);}*/// accessors -------------------------------------------------------// repeated int64 dim = 1 [packed = true]; // 对 dim 成员的操作inline int dim_size() const;	// 返回dim 列表大小inline void clear_dim();	// 清空static const int kDimFieldNumber = 1;	// *FieldNumber 的值对应 dim = 1 标识1inline ::google::protobuf::int64 dim(int index) const;	// 获取列表dim中指定索引的值inline void set_dim(int index, ::google::protobuf::int64 value); // 设置列表dim指定索引的值inline void add_dim(::google::protobuf::int64 value);	// 添加新元素到列表dim中inline const ::google::protobuf::RepeatedField< ::google::protobuf::int64 >& dim() const; // 返回dim的const引用，不可修改inline ::google::protobuf::RepeatedField< ::google::protobuf::int64 >*  mutable_dim();	// 返回dim的指针，可修改// @@protoc_insertion_point(class_scope:caffe.BlobShape)private:::google::protobuf::UnknownFieldSet _unknown_fields_;::google::protobuf::RepeatedField< ::google::protobuf::int64 > dim_;mutable int _dim_cached_byte_size_;mutable int _cached_size_;::google::protobuf::uint32 _has_bits_[(1 + 31) / 32];	// 1表示 message BlobShape中定义的成员个数为1friend void  protobuf_AddDesc_caffe_2eproto();friend void protobuf_AssignDesc_caffe_2eproto();friend void protobuf_ShutdownFile_caffe_2eproto();void InitAsDefaultInstance();static BlobShape* default_instance_;
};
// ===================================================================
// BlobShape对应的操作
// repeated int64 dim = 1 [packed = true];
inline int BlobShape::dim_size() const { //dim是列表形式，因此提供返回大小的接口return dim_.size();
}
inline void BlobShape::clear_dim() { // 清空dim_.Clear();
}
inline ::google::protobuf::int64 BlobShape::dim(int index) const { //获取指定索引的值return dim_.Get(index);
}
inline void BlobShape::set_dim(int index, ::google::protobuf::int64 value) { //设置指定索引的值dim_.Set(index, value);
}
inline void BlobShape::add_dim(::google::protobuf::int64 value) { //增量添加值到列表dim中dim_.Add(value);
}
inline const ::google::protobuf::RepeatedField< ::google::protobuf::int64 >&
BlobShape::dim() const { //返回只读dimreturn dim_;
}
inline ::google::protobuf::RepeatedField< ::google::protobuf::int64 >*
BlobShape::mutable_dim() { //返回可读写dimreturn &dim_;
}
......

【四】生成的caffe.pb.cc

略

【五】官网说明

谷歌官网说明：https://developers.google.com/protocol-buffers/
c++API手册：https://developers.google.com/protocol-buffers/docs/reference/cpp/#google.protobuf

【六】使用

1、将文本格式的 protobuf 读取到 Message 中

1.1 以 caffe 中 ReadProtoFromTextFile 为例

ReadProtoFromTextFile的调用步骤：
train() --> caffe::ReadSolverParamsFromTextFileOrDie(FLAGS_solver, &solver_param); --> ReadProtoFromTextFile(param_file, param)

1.2、ReadProtoFromTextFile 源码详解

bool ReadProtoFromTextFile(const char* filename, Message* proto) {int fd = open(filename, O_RDONLY);CHECK_NE(fd, -1) << "File not found: " << filename;FileInputStream* input = new FileInputStream(fd);bool success = google::protobuf::TextFormat::Parse(input, proto);delete input;close(fd);return success;
}

1.2.1 FileInputStream 详解
官方说明：

FileInputStream 继承自 ZeroCopyInputStream（从文件描述符读取流）

使用方法：（参考构建函数）

explicit FileInputStream(int file_descriptor, int block_size = -1);

参数：

	file_descriptor ： Unix 文件描述符block_size：指定 Next() 时读取和返回的大小，不指定时，将使用一个合理的默认值。

1.2.2 google::protobuf::TextFormat::Parse
TextFormat 类：

该类实现 protobuf 文本格式。以文本格式打印和解析协议消息对于调试和人工编辑消息非常有用。
这个类实际上是一个只包含静态方法的命名空间。

静态函数 Parse：

从给定的输入流解析 文本格式协议消息 到给定的 消息对象。这个函数解析Print()编写的格式。
static bool Parse(io::ZeroCopyInputStream* input, Message* output);

其它类似静态函数：

static bool ParseFromString(const string& input, Message* output);  // 直接从字符串解析
static bool Merge(io::ZeroCopyInputStream* input, Message* output); // 从流中解析，并合并到 Message 中，参见 Message::MergeFrom()
static bool MergeFromString(const string& input, Message* output);  // 同上，但是直接从字符串解析//解析单个字段值到指定的 message 的指定 field 字段中
static bool ParseFieldValueFromString(const string& input, const FieldDescriptor* field, Message* message); 

对应的反操作：将 Message 打印到流或文本中

static bool Print(const Message& message, io::ZeroCopyOutputStream* output); // 将 message 打印到输出流中
static bool PrintToString(const Message& message, string* output);	// 将 message 打印到字符串中// 将 message 指定的 field 字段，输出到字符串中。字段是列表格式时，指定引索 index；非列表格式时 index 必须指定为 -1
static void PrintFieldValueToString(const Message& message, const FieldDescriptor* field, int index, string* output); // 打印未知数集 UnknownFieldSet 中的字段。它们只按标签号打印。通过尝试解析嵌入的消息，可以直观地识别它们。
static bool PrintUnknownFields(const UnknownFieldSet& unknown_fields, io::ZeroCopyOutputStream* output); 

2、将 message 序列化到二进制文件中

2.1 以 caffe 中 WriteProtoToBinaryFile 函数为例

void WriteProtoToBinaryFile(const Message& proto, const char* filename) {fstream output(filename, ios::out | ios::trunc | ios::binary);CHECK(proto.SerializeToOstream(&output));	// 原型bool Message::SerializeToOstream(ostream* output) const; 将 Message 序列化到c++标准输出流中，必须设置所有必需字段。
}

2.2 序列化函数汇总：

// 将 Message 序列化到文件描述符中，必须设置所有必需字段。
bool SerializeToFileDescriptor(int file_descriptor) const;	// 同上，但是允许缺少必需的字段。	
bool SerializePartialToFileDescriptor(int file_descriptor) const;// 将 Message 序列化到c++标准输出流中，必须设置所有必需字段。
bool SerializeToOstream(ostream* output) const;	// 同上，但是允许缺少必需的字段。		
bool SerializePartialToOstream(ostream* output) const; 	

3、从二进制文件中 反序列化 到 message 中

3.1 以 caffe 中 ReadProtoFromBinaryFile 为例

bool ReadProtoFromBinaryFile(const char* filename, Message* proto) {int fd = open(filename, O_RDONLY);CHECK_NE(fd, -1) << "File not found: " << filename;ZeroCopyInputStream* raw_input = new FileInputStream(fd);CodedInputStream* coded_input = new CodedInputStream(raw_input);coded_input->SetTotalBytesLimit(kProtoReadBytesLimit, 536870912);bool success = proto->ParseFromCodedStream(coded_input);	// 原型 bool ParseFromCodedStream(io::CodedInputStream* input);delete coded_input;delete raw_input;close(fd);return success;
}

3.2 其它反序列化函数：

bool ParsePartialFromCodedStream(io::CodedInputStream* input);	// 同 ParseFromCodedStream ，但是接受缺少必需字段的消息。
bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);		// 从 io::ZeroCopyInputStream 流中获取
bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input); // 同上，但是接受缺少必需字段的消息。
bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size); // 同上，指定 message 大小必须是 size
bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, , int size); // 同上，但是接受缺少必需字段的消息。