From 57d830e6d962ae8af9243abcc7c36fc0c80a505b Mon Sep 17 00:00:00 2001 From: Jonathan Mace Date: Thu, 18 May 2017 17:28:56 -0400 Subject: [PATCH] Update some docs --- .../tracingplane/atomlayer/package-info.java | 12 ++++++-- .../java/brown/tracingplane/package-info.java | 30 +++++++++++++++++++ baggageprotocol/core/README.md | 5 ++++ .../baggageprotocol/package-info.java | 21 +++++++++++++ .../brown/tracingplane/bdl/package-info.java | 19 ++++++++++++ .../tracingplane/bdl/examples/Example.java | 0 6 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 baggagecontext/api/src/main/java/brown/tracingplane/package-info.java create mode 100644 baggageprotocol/core/README.md create mode 100644 baggageprotocol/core/src/main/java/brown/tracingplane/baggageprotocol/package-info.java create mode 100644 bdl/core/src/main/java/brown/tracingplane/bdl/package-info.java rename bdl/examples/src/{main => test}/java/brown/tracingplane/bdl/examples/Example.java (100%) diff --git a/atomlayer/core/src/main/java/brown/tracingplane/atomlayer/package-info.java b/atomlayer/core/src/main/java/brown/tracingplane/atomlayer/package-info.java index 346fc9f..1faf82c 100644 --- a/atomlayer/core/src/main/java/brown/tracingplane/atomlayer/package-info.java +++ b/atomlayer/core/src/main/java/brown/tracingplane/atomlayer/package-info.java @@ -1,12 +1,18 @@ /** * *

- * brown.tracingplane.atomlayer contains some of the core atom-based functions of the Tracing Plane, - * including implementations of lexicographic comparison and lexicographic merge. + * Provides the Tracing Plane's core underlying data representation for {@link BaggageContext} based on atoms and + * lexicographic merge. *

* *

- * In general, this code uses {@link ByteBuffer}s to represent atoms. + * The key primitives provided by the Atom Layer are an intermediary data format for {@link BaggageContext}s based on + * atoms, along with the default atom-based comparison and merge functions based on the lexicographic ordering of + * atoms. + *

+ * + *

+ * The Atom Layer represents atoms using {@link ByteBuffer}s. *

* *

diff --git a/baggagecontext/api/src/main/java/brown/tracingplane/package-info.java b/baggagecontext/api/src/main/java/brown/tracingplane/package-info.java new file mode 100644 index 0000000..a5eb224 --- /dev/null +++ b/baggagecontext/api/src/main/java/brown/tracingplane/package-info.java @@ -0,0 +1,30 @@ +/** + *

+ * Provides the main {@link BaggageContext} and {@link BaggageProvider} interfaces of the Tracing Plane + *

+ * + *

+ * At a high level, {@link BaggageContext} instances exist at the granularity of requests (or tasks, jobs, etc). The + * purpose is to propagate a {@link BaggageContext} alongside each request while it executes. {@link BaggageContext}s + * carry user-defined or tracing-tool defined data. + *

+ * + *

+ * {@link BaggageContext} instances should follow requests in a fine-grained manner. For example, if a request splits + * off into multiple concurrent execution branches, then each branch of execution should receive its its own + * {@link BaggageContext} instance, created by calling {@link BaggageProvider#branch(BaggageContext)} at the time the + * request splits. + *

+ * + *

+ * Likewise, if multiple concurrent branches merge, or if some task is dependent upon multiple predecessors completing, + * then {@link BaggageContext} instances can be merged using + * {@link BaggageProvider#join(BaggageContext, BaggageContext)}. + *

+ * + *

+ * The Tracing Plane provides several {@link BaggageContext} implementations, the main implementation being + * {@link brown.tracingplane.impl.BDLContext} in the {@link brown.tracingplane.bdl} package. + *

+ */ +package brown.tracingplane; diff --git a/baggageprotocol/core/README.md b/baggageprotocol/core/README.md new file mode 100644 index 0000000..06fc443 --- /dev/null +++ b/baggageprotocol/core/README.md @@ -0,0 +1,5 @@ +# Tracing Plane - Baggage Protocol + +The Baggage Protocol defines interfaces for nested data structures, along with an atom-based encoding scheme for the nested data structures. + +The encoding scheme is such that the Atom Layer's lexicographic merge behaves consistently with an equivalent object-level merge. \ No newline at end of file diff --git a/baggageprotocol/core/src/main/java/brown/tracingplane/baggageprotocol/package-info.java b/baggageprotocol/core/src/main/java/brown/tracingplane/baggageprotocol/package-info.java new file mode 100644 index 0000000..874843b --- /dev/null +++ b/baggageprotocol/core/src/main/java/brown/tracingplane/baggageprotocol/package-info.java @@ -0,0 +1,21 @@ +/** + *

+ * Defines an encoding scheme for nested data structures using atoms. + *

+ * + *

+ * The Baggage Protocol reads and writes {@link BaggageContext}s with a pre-order depth-first traversal. Starting from + * the root of the tree, we first have data for that node, followed by child nodes. Child nodes can be addressed by + * either statically defined indices, or by arbitrary-length key. + *

+ * + *

+ * The {@link BaggageReader} and {@link BaggageWriter} classes are used for reading and writing atoms for + * {@link BaggageContext} instances. + *

+ * + *

+ * Details of the baggage protocol can be found on the project GitHub repository. + *

+ */ +package brown.tracingplane.baggageprotocol; diff --git a/bdl/core/src/main/java/brown/tracingplane/bdl/package-info.java b/bdl/core/src/main/java/brown/tracingplane/bdl/package-info.java new file mode 100644 index 0000000..88a0230 --- /dev/null +++ b/bdl/core/src/main/java/brown/tracingplane/bdl/package-info.java @@ -0,0 +1,19 @@ +/** + *

+ * Library classes used by BDL-generated objects, including the {@link BDLContext} implementation of + * {@link BaggageContext}. + *

+ * + *

+ * The two main interfaces used by BDL are {@link Bag} and {@link BaggageHandler}. {@link Bag}s are nodes in the nested + * data structure tree, while {@link BaggageHandler}s provide branch, join, and serialization logic for {@link Bag}s. + * {@link Bag} and {@link BaggageHandler} are conceptually similar to {@link BaggageContext} and {@link BaggageProvider} + * , except applying to nodes within a {@link BDLContext}. + *

+ * + *

+ * The BDL library classes also include CRDT-like data structures that the BDL supports, such as counters, implemented + * by {@link CounterImpl}. + *

+ */ +package brown.tracingplane.bdl; diff --git a/bdl/examples/src/main/java/brown/tracingplane/bdl/examples/Example.java b/bdl/examples/src/test/java/brown/tracingplane/bdl/examples/Example.java similarity index 100% rename from bdl/examples/src/main/java/brown/tracingplane/bdl/examples/Example.java rename to bdl/examples/src/test/java/brown/tracingplane/bdl/examples/Example.java -- GitLab