From 98ec2d7008917485718ef365823affe30f0b4d50 Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Tue, 11 Jun 2019 14:51:20 -0700 Subject: [PATCH] modules/client/sync: Update README. --- modules/client/sync/README.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/modules/client/sync/README.md b/modules/client/sync/README.md index c569f07ac..be18bca46 100644 --- a/modules/client/sync/README.md +++ b/modules/client/sync/README.md @@ -32,11 +32,6 @@ again without any server-side state describing that token. When a `/sync` request is made, the `since` token is compared with the server's current sequence number. One of three branches is then taken: -- **Longpoll**: When the since token is 1 greater than the current sequence -number, the client enters _longpoll sync_: It waits for the next appropriate -event which is then sent immediately. The `next_batch` will then be 1 greater -than the sequence number of that event. - - **Linear**: When the since token's "delta" from the current sequence number ranges from 0 to some configurable limit (i.e 1024 or 4096), the client enters _linear sync_: an iteration of events between the `since` token and the current @@ -44,6 +39,12 @@ sequence is made where each event is tested for relevance to the client and a response is then made. If nothing was found for the client in this iteration, it falls back to _longpoll sync_ until an event comes through or timeout. +- **Longpoll**: When the since token is 1 greater than the current sequence +number, the client enters _longpoll sync_: It waits for the next appropriate +event which is then sent immediately. The `next_batch` will then be 1 greater +than the sequence number of that event. The implementation of _longpoll sync_ +is a specialization of _linear sync_, using the same handlers. + - **Polylog**: When the since token's "delta" exceeds the threshold for a _linear sync_ the client enters _polylog sync_. This is common when no `since` token is supplied at all (equal to 0) which is known as an initial @@ -61,9 +62,14 @@ events on the server. Each `/sync` module implements two primary functions: -- A simple boolean test of an event which determines if the client should -receive that event. This is intended to be invoked for the _longpoll_ and -_linear_ modes. - - A complex composer for a response in _polylog_ mode. This requires the -function itself to find all the events to include for a satisfying response. +handler itself to find all the events to include for a satisfying response. +This handler is invoked once for a `since` token during the single pass and +is responsible for building JSON inside the object the handler is responsible +for in the larger `/sync` tree. + +- A simple composer for a response in _linear_ mode. This requires the handler +to evaluate the event argument being passed. If the event is to be included +in the `/sync` response, the _linear_ handler builds a complete `/sync` JSON +object tree around this event, which indicates where it is placed in the `/sync` +tree.