commit 59715f2b82b6666951eb45a668f503468283892c
parent 6f699dcf8690d1df626ccc84bf0da6d07c612fd9
Author: nolash <dev@holbrook.no>
Date: Sun, 29 Aug 2021 10:57:32 +0200
Add filter, stack descriptions to infotex docs
Diffstat:
4 files changed, 91 insertions(+), 0 deletions(-)
diff --git a/doc/infotex/backend.texi b/doc/infotex/backend.texi
@@ -0,0 +1,37 @@
+@node chainsyncer-backend
+@section Backend implementations
+
+While syncing the chain, we need to keep track of where we are in the syncing process. The syncer backend is the pluggable component that records this state.
+
+The state consists of three parts, in hierarchical order:
+
+@enumerate
+@item Block height
+@item Transaction index in block
+@item Individual code filters to execute per transaction
+@end enumerate
+
+@subsection Syncer types
+
+By default there are two types of syncers.
+
+There is the @emph{live syncer} which continues to consume new blocks as they are available.
+
+There is also the @emph{history syncer} which syncs blocks between two specific points.
+
+A typical first-time syncer invocation defines a starting block height from which to retrieve blocks, in which case two syncers will be created;
+
+@itemize
+@item A history syncer syncing from the start height until the height at the time of the invocation.
+@item A live syncer syncing from the height at the time of the invocation, indefinitely retrieveing new blocks.
+@end itemize
+
+A typical resumed syncer invocation will involve additional syncers, depending on the state that was left off:
+
+@itemize
+@item History syncers for each previously incomplete history syncer run.
+@item A new history syncer resuming where the last live syncer left off, until the height at the time of invocation of the resume.
+@item A new live syncer syncing from the height at the time of the invocation, indefinitely retrieving new blocks.
+@end itemize
+
+In short, the consequence for the above is that one additional syncer will be spawned every time a syncer session is resumed.
diff --git a/doc/infotex/filter.texi b/doc/infotex/filter.texi
@@ -0,0 +1,25 @@
+@node chainsyncer-filter
+@section Syncer filter
+
+A filter is a piece of code that gets executed for every transaction in a block.
+
+The filter will receive the block and transaction data, aswell as an RPC and syncer backend connection. This enables the code interact with the blockchain node provisioning the chain context of the syncer session, aswell as all chain-specific details of the specific block and transaction at the current syncer state.
+
+
+@subsection Filter execution state
+
+The syncer keeps track of which filters have been executed for which transaction.
+
+Every filter added to the syncer adds a new bit to a bit field constituting a filter flag. When a filter has finished executing, the bit corresponding to the filter's index in the syncer filter array should be set and stored.
+
+Since atomicity across code execution and flag setting cannot be guaranteed, it is the implementer's responsibility to ensure that a @emph{started} filter execution actually has been @emph{completed}. If proper care is not taken, individual filter code @emph{may} be run twice for a particular transaction.
+
+Allowing for disambiguation between started and completed filters should be in scope for imminent improvement of the syncer package.
+
+
+@subsection Integrity protection
+
+Backends may optionally enable filter integrity protection. In practice this means that if a specific syncer session was started with a specific collection of filters, the syncer session may not be resumed with a different collection of filters.
+
+Depending on the implementation, the collection of filters may or may not be dependent on the order in which they are added.
+
diff --git a/doc/infotex/index.texi b/doc/infotex/index.texi
@@ -0,0 +1,7 @@
+@top chainsyncer
+
+@chapter Chainsyncer
+
+@include backend.texi
+@include stack.texi
+@include filter.texi
diff --git a/doc/infotex/stack.texi b/doc/infotex/stack.texi
@@ -0,0 +1,22 @@
+@node chainsyncer-stack
+@section Syncer driver stack
+
+The chainsyncer package defines a generic syncer stack intended to cover most circumstances.
+
+The default implementation is single-threaded. This means that block and block transactions will be processed sequentially.
+
+It is defined as follows, in order of inheritance:
+
+@table @code
+@item chainsyncer.driver.base.Syncer
+Base syncer object, providing base properties and flow control
+@item chainsyncer.driver.poll.BlockPollSyncer
+Polling block retriever, defining the main loop and callback logic
+@item chainsyncer.driver.head.HeadSyncer
+Applied open-ended syncer settings, and defines the processing of a single block
+@item chainsyncer.driver.history.HistorySyncer
+Builds on chainsyncer.driver.head.HeadSyncer, and differs only in the fact that block not found is considered an error, and reaching the target block is considered a normal termination of the syncer loop.
+@end table
+
+Additionally, asynchronous driver modules exist in the codebase. These are still considered as experimental, and will only be documented once considered semi-stable.
+
