BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-13 00:04:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Port FlatBuffers to Go.

Browse Source 
Implement code generation and runtime library for Go, derived from the
Java implementation. Additionally, the test suite verifies:

 - the exact bytes in the Builder buffer during object construction,
 - vtable deduplication, and
 - table construction, via a fuzzer derived from the C++ implementation.

Change-Id: Ib95a019c684891def2b50281e570b4843fea7baa
This commit is contained in:
rw
2014-07-11 16:12:35 -07:00
committed by Wouter van Oortmerssen
parent 3fb6a86d02
commit 74d5f3701f
36 changed files with 3631 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/html/index.html
View File

@@ -53,7 +53,7 @@ $(document).ready(function(){initNavTree('index.html','');});
<div class="title">FlatBuffers Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>FlatBuffers is an efficient cross platform serialization library in for C++ and Java. It was created at Google specifically for game development and other performance-critical applications.</p>
<div class="textblock"><p>FlatBuffers is an efficient cross platform serialization library for C++, with support for Java and Go. It was created at Google specifically for game development and other performance-critical applications.</p>
<p>It is available as open source under the Apache license, v2 (see LICENSE.txt).</p>
<h2>Why use FlatBuffers?</h2>
<ul>
@@ -63,9 +63,9 @@ $(document).ready(function(){initNavTree('index.html','');});
<li><b>Tiny code footprint</b> - Small amounts of generated code, and just a single small header as the minimum dependency, which is very easy to integrate. Again, see the benchmark section for details.</li>
<li><b>Strongly typed</b> - Errors happen at compile time rather than manually having to write repetitive and error prone run-time checks. Useful code can be generated for you.</li>
<li><p class="startli"><b>Convenient to use</b> - Generated C++ code allows for terse access &amp; construction code. Then there's optional functionality for parsing schemas and JSON-like text representations at runtime efficiently if needed (faster and more memory efficient than other JSON parsers).</p>
<p class="startli">Java code supports object-reuse.</p>
<p class="startli">Java and Go code supports object-reuse.</p>
</li>
<li><b>Cross platform C++11/Java code with no dependencies</b> - will work with any recent gcc/clang and VS2010. Comes with build files for the tests &amp; samples (Android .mk files, and cmake for all other platforms).</li>
<li><b>Cross platform C++11/Java/Go code with no dependencies</b> - will work with any recent gcc/clang and VS2010. Comes with build files for the tests &amp; samples (Android .mk files, and cmake for all other platforms).</li>
</ul>
<h3>Why not use Protocol Buffers, or .. ?</h3>
<p>Protocol Buffers is indeed relatively similar to FlatBuffers, with the primary difference being that FlatBuffers does not need a parsing/ unpacking step to a secondary representation before you can access data, often coupled with per-object memory allocation. The code is an order of magnitude bigger, too. Protocol Buffers has neither optional text import/export nor schema language features like unions.</p>
@@ -76,7 +76,7 @@ $(document).ready(function(){initNavTree('index.html','');});
<p>This section is a quick rundown of how to use this system. Subsequent sections provide a more in-depth usage guide.</p>
<ul>
<li>Write a schema file that allows you to define the data structures you may want to serialize. Fields can have a scalar type (ints/floats of all sizes), or they can be a: string; array of any type; reference to yet another object; or, a set of possible objects (unions). Fields are optional and have defaults, so they don't need to be present for every object instance.</li>
<li>Use <code>flatc</code> (the FlatBuffer compiler) to generate a C++ header (or Java classes) with helper classes to access and construct serialized data. This header (say <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
<li>Use <code>flatc</code> (the FlatBuffer compiler) to generate a C++ header (or Java/Go classes) with helper classes to access and construct serialized data. This header (say <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
<li>Use the <code>FlatBufferBuilder</code> class to construct a flat binary buffer. The generated functions allow you to add objects to this buffer recursively, often as simply as making a single function call.</li>
<li>Store or send your buffer somewhere!</li>
<li>When reading it back, you can obtain the pointer to the root object from the binary buffer, and from there traverse it conveniently in-place with <code>object-&gt;field()</code>.</li>
@@ -88,6 +88,7 @@ $(document).ready(function(){initNavTree('index.html','');});
<li>How to <a href="md__schemas.html">write a schema</a>.</li>
<li>How to <a href="md__cpp_usage.html">use the generated C++ code</a> in your own programs.</li>
<li>How to <a href="md__java_usage.html">use the generated Java code</a> in your own programs.</li>
<li>How to <a href="md__go_usage.html">use the generated Go code</a> in your own programs.</li>
<li>Some <a href="md__benchmarks.html">benchmarks</a> showing the advantage of using FlatBuffers.</li>
<li>A <a href="md__white_paper.html">white paper</a> explaining the "why" of FlatBuffers.</li>
<li>A description of the <a href="md__internals.html">internals</a> of FlatBuffers.</li>

106
docs/html/md__go_usage.html Normal file
View File

@@ -0,0 +1,106 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Use in Go</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__go_usage.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Use in Go </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There's experimental support for reading FlatBuffers in Go. Generate code for Go with the <code>-g</code> option to <code>flatc</code>.</p>
<p>See <code>go_test.go</code> for an example. You import the generated code, read a FlatBuffer binary file into a <code>[]byte</code>, which you pass to the <code>GetRootAsMonster</code> function: </p><pre class="fragment">import (
example "MyGame/Example"
flatbuffers "github.com/google/flatbuffers/go"
io/ioutil
)
buf, err := ioutil.ReadFile("monster.dat")
// handle err
monster := example.GetRootAsMonster(buf, 0)
</pre><p>Now you can access values like this: </p><pre class="fragment">hp := monster.Hp()
pos := monster.Pos(nil)
</pre><p>Note that whenever you access a new object like in the <code>Pos</code> example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), you can replace nil with a pointer to a <code>Vec3</code> object you've already created. This allows you to reuse it across many calls and reduce the amount of object allocation (and thus garbage collection) your program does.</p>
<p>To access vectors you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by <code>Length</code> let's you know the number of elements you can access: </p><pre class="fragment">for i := 0; i &lt; monster.InventoryLength(); i++ {
monster.Inventory(i) // do something here
}
</pre><p>You can also construct these buffers in Go using the functions found in the generated code, and the FlatBufferBuilder class: </p><pre class="fragment">builder := flatbuffers.NewBuilder(0)
</pre><p>Create strings: </p><pre class="fragment">str := builder.CreateString("MyMonster")
</pre><p>Create a table with a struct contained therein: </p><pre class="fragment">example.MonsterStart(builder)
example.MonsterAddPos(builder, example.CreateVec3(builder, 1.0, 2.0, 3.0, 3.0, 4, 5, 6))
example.MonsterAddHp(builder, 80)
example.MonsterAddName(builder, str)
example.MonsterAddInventory(builder, inv)
example.MonsterAddTest_Type(builder, 1)
example.MonsterAddTest(builder, mon2)
example.MonsterAddTest4(builder, test4s)
mon := example.MonsterEnd(builder)
</pre><p>Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the <code>Vec3</code> is an inline component of <code>Monster</code>, it has to be created right where it is added, whereas the name and the inventory are not inline). Structs do have convenient methods that allow you to construct them in one call. These even have arguments for nested structs, e.g. if a struct has a field <code>a</code> and a nested struct field <code>b</code> (which has fields <code>c</code> and <code>d</code>), then the arguments will be <code>a</code>, <code>c</code> and <code>d</code>.</p>
<p>Vectors also use this start/end pattern to allow vectors of both scalar types and structs: </p><pre class="fragment">example.MonsterStartInventoryVector(builder, 5)
for i := 4; i &gt;= 0; i-- {
builder.PrependByte(byte(i))
}
inv := builder.EndVector(5)
</pre><p>The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.</p>
<p>There are <code>Prepend</code> functions for all the scalar types. You use <code>PrependUOffset</code> for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate <code>create</code> function in-line, as shown above in the <code>Monster</code> example.</p>
<h2>Text Parsing</h2>
<p>There currently is no support for parsing text (Schema's and JSON) directly from Go, though you could use the C++ parser through cgo. Please see the C++ documentation for more on text parsing. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>

1
docs/html/navtree.js
View File

@@ -5,6 +5,7 @@ var NAVTREE =
[ "Using the schema compiler", "md__compiler.html", null ],
[ "Writing a schema", "md__schemas.html", null ],
[ "Use in C++", "md__cpp_usage.html", null ],
[ "Use in Go", "md__go_usage.html", null ],
[ "Use in Java", "md__java_usage.html", null ],
[ "Benchmarks", "md__benchmarks.html", null ],
[ "FlatBuffers white paper", "md__white_paper.html", null ],

11
docs/html/navtreeindex0.js
View File

@@ -1,14 +1,15 @@
var NAVTREEINDEX0 =
{
"index.html":[],
"md__benchmarks.html":[5],
"md__benchmarks.html":[6],
"md__building.html":[0],
"md__compiler.html":[1],
"md__cpp_usage.html":[3],
"md__grammar.html":[8],
"md__internals.html":[7],
"md__java_usage.html":[4],
"md__go_usage.html":[4],
"md__grammar.html":[9],
"md__internals.html":[8],
"md__java_usage.html":[5],
"md__schemas.html":[2],
"md__white_paper.html":[6],
"md__white_paper.html":[7],
"pages.html":[]
};

11
docs/html/pages.html
View File

@@ -59,11 +59,12 @@ $(document).ready(function(){initNavTree('pages.html','');});
<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__compiler.html" target="_self">Using the schema compiler</a></td><td class="desc"></td></tr>
<tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__schemas.html" target="_self">Writing a schema</a></td><td class="desc"></td></tr>
<tr id="row_3_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__cpp_usage.html" target="_self">Use in C++</a></td><td class="desc"></td></tr>
<tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__java_usage.html" target="_self">Use in Java</a></td><td class="desc"></td></tr>
<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr>
<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr>
<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr>
<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__grammar.html" target="_self">Formal Grammar of the schema language</a></td><td class="desc"></td></tr>
<tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__go_usage.html" target="_self">Use in Go</a></td><td class="desc"></td></tr>
<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__java_usage.html" target="_self">Use in Java</a></td><td class="desc"></td></tr>
<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr>
<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr>
<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr>
<tr id="row_9_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__grammar.html" target="_self">Formal Grammar of the schema language</a></td><td class="desc"></td></tr>
</table>
</div><!-- directory -->
</div><!-- contents -->