diff options
author | Lawrence Chan <llchan@users.noreply.github.com> | 2017-06-07 15:56:49 -0500 |
---|---|---|
committer | Wouter van Oortmerssen <aardappel@gmail.com> | 2017-06-07 13:56:49 -0700 |
commit | da67c0a71f98b8bab59aacd424b8648a9e293476 (patch) | |
tree | 7bd7ab93e57bb179f85f9f7858d033490c69eebe /docs | |
parent | dadd1a926ee75cad9d9ef792edcbc902b1f1744a (diff) | |
download | flatbuffers-da67c0a71f98b8bab59aacd424b8648a9e293476.tar.gz |
[C++] Improve flatbuffers + gRPC integration (#4310)
* Rework flatbuffers + gRPC integration
- Introduce `flatbuffers::grpc::Message<T>`, a `grpc_slice`-backed
message buffer that handles refcounting and allows flatbuffers to
transfer ownership to gRPC efficiently. This replaces
`flatbuffers::BufferRef<T>`, which required a copy call and was also
unsafe w.r.t. buffer lifetime.
- Introduce `flatbuffers::grpc::MessageBuilder`, a gRPC-specific builder
that forces a `grpc_slice`-backed allocator and also adds some helpful
`Message<T>`-related methods.
- Update serializers accordingly (now zero-copy between flatbuffers and
gRPC).
* gRPC: verify messages by default, but allow user to override
* gRPC: fix some formatting issues
* Disable verification by default, but add helper method
* Make FlatBufferBuilder fields protected + remove vec accessor
* Use bool add_ref parameter to toggle refcount incr
* Remove unnecessary inline specifiers
* Fix formatting
* Use auto
* Remove empty lines
* Use grpc_slice helper macros
* Simplify reset code
* Disable Message copy ctor and assignment by default
* Remove unused member
* Enable gRPC verification by default
* Use auto
* Bake in message verification (remove template specialization)
* Add RoundUp func
* Consolidate gRPC message copy flag
* Make vector_downward allocations fully lazy
* Test message verification failure code/message
* Add grpctest verification test comments
* Simplify reallocate implementation
* Make initial_size a size_t
* Use ternary op for growth_policy
* Use truthiness rather than dont explicit nullptr check
* Indent preprocessor directives
* Remove grpc message copy/assignment
* Fix a few bugs
* Add gRPC example
* Add basic gRPC docs
* Use doxygen EXAMPLE_PATH + @include
* Reference example fbs in grpc docs
* Move gRPC examples into grpc/samples
* Fix pointer/reference formatting
* Use std::function rather than templated callback func
* Create fresh message builder for each request
* Use Clear() in Reset() impl
* Use FLATBUFFERS_CONSTEXPR
Diffstat (limited to 'docs')
-rwxr-xr-x | docs/source/doxyfile | 7 | ||||
-rw-r--r-- | docs/source/doxygen_layout.xml | 4 | ||||
-rw-r--r-- | docs/source/gRPC/CppUsage.md | 29 |
3 files changed, 37 insertions, 3 deletions
diff --git a/docs/source/doxyfile b/docs/source/doxyfile index 770da9f2..64af6710 100755 --- a/docs/source/doxyfile +++ b/docs/source/doxyfile @@ -765,6 +765,7 @@ INPUT = "FlatBuffers.md" \ "../../CONTRIBUTING.md" \ "Tutorial.md" \ "GoApi.md" \ + "gRPC/CppUsage.md" \ "groups" \ "../../java/com/google/flatbuffers" \ "../../python/flatbuffers/builder.py" \ @@ -883,21 +884,21 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = "GoApi_generated.txt" +EXAMPLE_PATH = "GoApi_generated.txt" "../../grpc/samples" # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = * +EXAMPLE_PATTERNS = *.cpp *.h *.txt *.fbs # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands # irrespective of the value of the RECURSIVE tag. # The default value is: NO. -EXAMPLE_RECURSIVE = NO +EXAMPLE_RECURSIVE = YES # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the diff --git a/docs/source/doxygen_layout.xml b/docs/source/doxygen_layout.xml index 77866df3..504d15c1 100644 --- a/docs/source/doxygen_layout.xml +++ b/docs/source/doxygen_layout.xml @@ -39,6 +39,10 @@ title="Use in Python"/> <tab type="user" url="@ref flexbuffers" title="Schema-less version"/> + <tab type="usergroup" url="" title="gRPC"> + <tab type="user" url="@ref flatbuffers_grpc_guide_use_cpp" + title="Use in C++"/> + </tab> </tab> <tab type="user" url="@ref flatbuffers_support" title="Platform / Language / Feature support"/> diff --git a/docs/source/gRPC/CppUsage.md b/docs/source/gRPC/CppUsage.md new file mode 100644 index 00000000..93dbb299 --- /dev/null +++ b/docs/source/gRPC/CppUsage.md @@ -0,0 +1,29 @@ +Use in C++ {#flatbuffers_grpc_guide_use_cpp} +========== + +## Before you get started + +Before diving into the FlatBuffers gRPC usage in C++, you should already be +familiar with the following: + +- FlatBuffers as a serialization format +- [gRPC](http://www.grpc.io/docs/) usage + +## Using the FlatBuffers gRPC C++ library + +NOTE: The examples below are also in the `grpc/samples/greeter` directory. + +We will illustrate usage with the following schema: + +@include grpc/samples/greeter/greeter.fbs + +When we run `flatc`, we pass in the `--grpc` option and generage an additional +`greeter.grpc.fb.h` and `greeter.grpc.fb.cc`. + +Example server code looks like this: + +@include grpc/samples/greeter/server.cpp + +Example client code looks like this: + +@include grpc/samples/greeter/client.cpp |