Document new access order checking feature.

Author: ZachBray

Change-Log.md

@@ -1,3 +1,6 @@
+### vNext
+* [Java, C++, C#] Add support to [check the safe usage of flyweights (w.r.t. field access order)](./Safe-Flyweight-Usage). [PR #948](https://github.com/real-logic/simple-binary-encoding/pull/948).
+
 ### 1.27.0 (11 Oct 2022)
 * [Java] Add preview support for package override on types from SBE 2.0. [PR #904](https://github.com/real-logic/simple-binary-encoding/pull/904), [PR #915](https://github.com/real-logic/simple-binary-encoding/pull/915).
 * Add support for transforming a schema to generate code for older versions when checking compatibility.

Home.md

@@ -13,6 +13,7 @@ The SBE tool can be used as a library enabling on-the-fly decoding of messages,
 1. [C++ Users Guide](wiki/Cpp-User-Guide)
 1. [CSharp Users Guide](wiki/CSharp-User-Guide)
 1. [Golang Users Guide](wiki/Golang-User-Guide)
+1. [Safe Flyweight Usage](wiki/Safe-Flyweight-Usage)
 1. [FIX/SBE XML Primer](wiki/FIX-SBE-XML-Primer)
 1. [Message Extension/Versioning](wiki/Message-Versioning)
 1. [Intermediate Representation](wiki/Intermediate-Representation)

Safe-Flyweight-Usage.md

@@ -0,0 +1,98 @@
+The encoders and decoders that SBE generates in Java (and other languages without approximations of session types) require developers to follow a strict contract:
+
+- Developers must encode/decode all repeating groups and variable-length data fields in the order in which they appear in the schema.
+- Developers must explicitly encode/decode/skip all present groups and variable-length data, i.e., no implicit skipping.
+- Developers must call next() before encoding/decoding each repeating group element.
+
+When encoding, failure to follow the contract can produce invalid messages that do not conform to the format described in the associated SBE schema.
+
+When decoding, failure to follow the contract can result in the misinterpretation of valid messages.
+
+### Checking field access order
+
+SBE can generate runtime checks that ensure the correct usage of flyweight encoders/decoders/codecs (w.r.t. field access order) in Java, C++ and C#.
+
+To generate these runtime checks, pass `-Dsbe.generate.access.order.checks=true` when running the SBE tool.
+
+By default, the generated checks are disabled, using conditional compilation, as they have a significant performance overhead. When running our car benchmarks, we see approximately 50% fewer encodes/decodes per second.
+We expect that teams will enable these runtime checks in non-production environments and in their tests.
+
+To enable the runtime checks:
+
+* In Java, set the `sbe.generate.access.order.checks` system property to `true`.
+* In C++, define the `ENABLE_ACCESS_ORDER_CHECKS` symbol when compiling.
+* In C#, define the `ENABLE_ACCESS_ORDER_CHECKS` symbol when building.
+
+### Checking complete encoding
+
+When runtime checks are enabled, in addition to checking fields are encoded/decoded in the correct order, you can also check that you've fully encoded a message. I.e., that you haven't omitted any groups or variable length fields from the end of the message.
+To do so, call the `checkEncodingIsComplete()` method on the flyweight encoder for the message.
+
+### Understanding errors
+
+Once runtime checks are enabled, you may start to see some errors if you have some incorrect (or very unusual) uses of flyweight encoders/decoders/codecs.
+
+For example, if you have a message schema with two variable length fields:
+
+```xml
+<sbe:message name="SendChatMessage" id="99">
+    <field name="chatId" id="1" type="int64"/>
+    <data name="subject" id="2" type="varDataEncoding"/> <!-- subject first -->
+    <data name="body" id="3" type="varDataEncoding"/>    <!-- body second -->
+</sbe:message>
+```
+
+and you accidentally encode these in a different order to the schema:
+
+```java
+final SendChatMessageEncoder encoder = new SendChatMessageEncoder()
+    .wrapAndApplyHeader(buffer, OFFSET, messageHeaderEncoder);
+
+encoder.chatId(1)
+    .body("About 1 ft tall and furry.") // body first
+    .subject("Missing cat");            // subject second
+```
+
+you will an exception like this one at runtime:
+
+```
+Illegal field access order.
+Cannot access field "body" in state: V0_BLOCK.
+Expected one of these transitions: ["chatId(?)", "subject(?)"].
+Please see the diagram in the Javadoc of the inner class #CodecStates.
+```
+
+The exception tells us:
+
+- The current codec state is `V0_BLOCK`.
+- We cannot call `body` when the codec is in this state.
+- But we can call either `chatId` or `subject` in this state.
+
+It also says where we can find more information. The `CodecStates` class documentation holds a dot diagram of the state machine:
+
+```java
+    /**
+     * The states in which a encoder/decoder/codec can live.
+     *
+     * <p>The state machine diagram below, encoded in the dot language, describes
+     * the valid state transitions according to the order in which fields may be
+     * accessed safely. Tools such as PlantUML and Graphviz can render it.
+     *
+     * <pre>{@code
+     *   digraph G {
+     *       NOT_WRAPPED -> V0_BLOCK [label="  wrap(version=0)  "];
+     *       V0_BLOCK -> V0_BLOCK [label="  chatId(?)  "];
+     *       V0_BLOCK -> V0_SUBJECT_DONE [label="  subject(?)  "];
+     *       V0_SUBJECT_DONE -> V0_BODY_DONE [label="  body(?)  "];
+     *   }
+     * }</pre>
+     */
+    private static class CodecStates
+    {
+        // ...
+    }
+ ```
+
+ We can use a tool, e.g., [PlantText](http://planttext.com), to render the dot diagram and reveal the state machine diagram.
+
+ ![State Machine Example](./State-Machine-Example.png)

Sbe-Tool-Guide.md

@@ -25,6 +25,8 @@ The tool supports the following options:
  * `sbe.keyword.append.token`: String to append to schema tokens that collide with reserved words in the target language.
  * `sbe.decode.unknown.enum.values`: Support unknown decoded enum values.
  * `sbe.csharp.generate.namespace.dir`: Should a directory be created for the namespace under the output directory? Defaults to `true`.
+ * `sbe.generate.access.order.checks`: Generate code to check flyweight methods are accessed in a valid order? Defaults to `false`. This option is supported by the Java, C#, and C++ generators. Requires platform-specific configuration to enable the checks at runtime, e.g., setting a system property or constant symbol.
+ * `sbe.cpp.disable.implicit.copying`: Disable generation of copy constructors and copy assignment operators? Defaults to `false`. 
 
 The SBE tool can be used with Maven
 [see](https://github.com/real-logic/simple-binary-encoding/wiki/Sbe-Tool-Maven)