From ff0d7a89d87eb88786e99a3e23a107695fa832a1 Mon Sep 17 00:00:00 2001 From: Wouter van Oortmerssen Date: Mon, 23 Jun 2014 13:33:34 -0700 Subject: [PATCH] Doc clarifications (Java vectors, test working dir, benchmark fix). Change-Id: If8cc05669d82df892e1d4e11f7fbbd68b2dc05bf --- docs/html/md__benchmarks.html | 4 ++-- docs/html/md__building.html | 3 ++- docs/html/md__java_usage.html | 2 ++ docs/source/Benchmarks.md | 4 ++-- docs/source/Building.md | 8 +++++--- docs/source/JavaUsage.md | 11 +++++++++++ 6 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/html/md__benchmarks.html b/docs/html/md__benchmarks.html index 3cedadc..3a8a601 100644 --- a/docs/html/md__benchmarks.html +++ b/docs/html/md__benchmarks.html @@ -60,9 +60,9 @@ $(document).ready(function(){initNavTree('md__benchmarks.html','');}); FlatBuffers (binary) Protocol Buffers LITE Rapid JSON FlatBuffers (JSON) -Decode + Traverse + Dealloc (1 million times, seconds) 0.08 305 583 105 +Decode + Traverse + Dealloc (1 million times, seconds) 0.08 302 583 105 -Decode / Traverse / Dealloc (breakdown) 0 / 0.08 / 0 220 / 3.6 / 81 294 / 0.9 / 287 70 / 0.08 / 35 +Decode / Traverse / Dealloc (breakdown) 0 / 0.08 / 0 220 / 0.15 / 81 294 / 0.9 / 287 70 / 0.08 / 35 Encode (1 million times, seconds) 3.2 185 650 169 diff --git a/docs/html/md__building.html b/docs/html/md__building.html index a32ad3a..2f03d75 100644 --- a/docs/html/md__building.html +++ b/docs/html/md__building.html @@ -58,7 +58,8 @@ $(document).ready(function(){initNavTree('md__building.html','');}); cmake -G "Visual Studio 10" cmake -G "Xcode"

Then, build as normal for your platform. This should result in a flatc executable, essential for the next steps. Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles".

-

Optionally, run the flattests executable. to ensure everything is working correctly on your system. If this fails, please contact us!

+

Optionally, run the flattests executable to ensure everything is working correctly on your system. If this fails, please contact us!

+

Note that you MUST be in the root of the FlatBuffers distribution when you run 'flattests' (and the samples), or it will fail to load its files.

Building should also produce two sample executables, sample_binary and sample_text, see the corresponding .cpp file in the samples directory.

There is an android directory that contains all you need to build the test executable on android (use the included build_apk.sh script, or use ndk_build / adb etc. as usual). Upon running, it will output to the log if tests succeeded or not.

There is usually no runtime to compile, as the code consists of a single header, include/flatbuffers/flatbuffers.h. You should add the include folder to your include paths. If you wish to be able to load schemas and/or parse text into binary buffers at runtime, you additionally need the other headers in include/flatbuffers. You must also compile/link src/idl_parser.cpp (and src/idl_gen_text.cpp if you also want to be able convert binary to text).

diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html index 27aae1b..44e30e5 100644 --- a/docs/html/md__java_usage.html +++ b/docs/html/md__java_usage.html @@ -59,6 +59,7 @@ Monster monster = Monster.getRootAsMonster(bb);

Now you can access values much like C++: 

short hp = monster.hp();
 Vec3 pos = monster.pos();

Note that whenever you access a new object like in the pos example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), there's a second pos() method to which you can pass a Vec3 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.

+

Java does not support unsigned scalars. This means that any unsigned types you use in your schema will actually be represented as a signed value. This means all bits are still present, but may represent a negative value when used. For example, to read a byte b as an unsigned number, you can do: (short)(b & 0xFF)

Sadly the string accessors currently always create a new string when accessed, since FlatBuffer's UTF-8 strings can't be read in-place by Java.

Vector access is also a bit different from C++: you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by _length let's you know the number of elements you can access: 

for (int i = 0; i < monster.inventory_length(); i++)
     monster.inventory(i); // do something here
@@ -78,6 +79,7 @@ int mon = Monster.endMonster(fbb);
 for (byte i = 4; i >=0; i--) fbb.addByte(i);
 int inv = fbb.endVector();

You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.

+

There are add functions for all the scalar types. You use addOffset for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate create function in-line, as shown above in the Monster example.

Text Parsing

There currently is no support for parsing text (Schema's and JSON) directly from Java, though you could use the C++ parser through JNI. Please see the C++ documentation for more on text parsing.

diff --git a/docs/source/Benchmarks.md b/docs/source/Benchmarks.md index c57e6ff..85305cb 100755 --- a/docs/source/Benchmarks.md +++ b/docs/source/Benchmarks.md @@ -15,8 +15,8 @@ meant to be representative of game data, e.g. a scene format. | | FlatBuffers (binary) | Protocol Buffers LITE | Rapid JSON | FlatBuffers (JSON) | |--------------------------------------------------------|-----------------------|-----------------------|-----------------------|-----------------------| -| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08 | 305 | 583 | 105 | -| Decode / Traverse / Dealloc (breakdown) | 0 / 0.08 / 0 | 220 / 3.6 / 81 | 294 / 0.9 / 287 | 70 / 0.08 / 35 | +| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08 | 302 | 583 | 105 | +| Decode / Traverse / Dealloc (breakdown) | 0 / 0.08 / 0 | 220 / 0.15 / 81 | 294 / 0.9 / 287 | 70 / 0.08 / 35 | | Encode (1 million times, seconds) | 3.2 | 185 | 650 | 169 | | Wire format size (normal / zlib, bytes) | 344 / 220 | 228 / 174 | 1475 / 322 | 1029 / 298 | | Memory needed to store decoded wire (bytes / blocks) | 0 / 0 | 760 / 20 | 65689 / 40 | 328 / 1 | diff --git a/docs/source/Building.md b/docs/source/Building.md index 8cbc78d..f2e1818 100755 --- a/docs/source/Building.md +++ b/docs/source/Building.md @@ -18,9 +18,11 @@ Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"`. -Optionally, run the `flattests` executable. -to ensure everything is working correctly on your system. If this fails, -please contact us! +Optionally, run the `flattests` executable to ensure everything is working +correctly on your system. If this fails, please contact us! + +Note that you MUST be in the root of the FlatBuffers distribution when you +run 'flattests' (and the samples), or it will fail to load its files. Building should also produce two sample executables, `sample_binary` and `sample_text`, see the corresponding `.cpp` file in the samples directory. diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md index 10828b7..f231a2f 100755 --- a/docs/source/JavaUsage.md +++ b/docs/source/JavaUsage.md @@ -22,6 +22,12 @@ method to which you can pass a `Vec3` 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. +Java does not support unsigned scalars. This means that any unsigned types you +use in your schema will actually be represented as a signed value. This means +all bits are still present, but may represent a negative value when used. +For example, to read a `byte b` as an unsigned number, you can do: +`(short)(b & 0xFF)` + Sadly the string accessors currently always create a new string when accessed, since FlatBuffer's UTF-8 strings can't be read in-place by Java. @@ -72,6 +78,11 @@ You can use the generated method `startInventoryVector` to conveniently call elements you want to write. You write the elements backwards since the buffer is being constructed back to front. +There are `add` functions for all the scalar types. You use `addOffset` for +any previously constructed objects (such as other tables, strings, vectors). +For structs, you use the appropriate `create` function in-line, as shown +above in the `Monster` example. + ## Text Parsing There currently is no support for parsing text (Schema's and JSON) directly -- 2.7.4