Commit 57d830e6 authored by Jonathan Mace's avatar Jonathan Mace

Update some docs

parent b4969fbb
/**
*
* <p>
* <code>brown.tracingplane.atomlayer</code> 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 <i>atoms</i> and
* <i>lexicographic merge</i>.
* </p>
*
* <p>
* 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
* <i>atoms</i>, along with the default atom-based comparison and merge functions based on the lexicographic ordering of
* atoms.
* </p>
*
* <p>
* The Atom Layer represents atoms using {@link ByteBuffer}s.
* </p>
*
* <p>
......
/**
* <p>
* Provides the main {@link BaggageContext} and {@link BaggageProvider} interfaces of the Tracing Plane
* </p>
*
* <p>
* 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.
* </p>
*
* <p>
* {@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.
* </p>
*
* <p>
* 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)}.
* </p>
*
* <p>
* The Tracing Plane provides several {@link BaggageContext} implementations, the main implementation being
* {@link brown.tracingplane.impl.BDLContext} in the {@link brown.tracingplane.bdl} package.
* </p>
*/
package brown.tracingplane;
# 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
/**
* <p>
* Defines an encoding scheme for nested data structures using atoms.
* </p>
*
* <p>
* 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.
* </p>
*
* <p>
* The {@link BaggageReader} and {@link BaggageWriter} classes are used for reading and writing atoms for
* {@link BaggageContext} instances.
* </p>
*
* <p>
* Details of the baggage protocol can be found on the project GitHub repository.
* </p>
*/
package brown.tracingplane.baggageprotocol;
/**
* <p>
* Library classes used by BDL-generated objects, including the {@link BDLContext} implementation of
* {@link BaggageContext}.
* </p>
*
* <p>
* 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}.
* </p>
*
* <p>
* The BDL library classes also include CRDT-like data structures that the BDL supports, such as counters, implemented
* by {@link CounterImpl}.
* </p>
*/
package brown.tracingplane.bdl;
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment