Improve ProgressTracker class javadoc

Previously it was mentioning only "frontend" and "backend".
Now it also mentions "users", to distinguish opening and closing tasks
(which happens on user-frontend boundary) from reconnect scenarios
(which happen on frontend-backend boundary).

Change-Id: I2e1739ac40d9e1b0661d9de42099fd97e816585c
Signed-off-by: Vratko Polak <vrpolak@cisco.com>

diff --git a/opendaylight/md-sal/cds-access-client/src/main/java/org/opendaylight/controller/cluster/access/client/ProgressTracker.java b/opendaylight/md-sal/cds-access-client/src/main/java/org/opendaylight/controller/cluster/access/client/ProgressTracker.java
index 15bfa569a22e4e8589e200d998d2588bb52b5471..b4fb3264d18c7f7fd1946f3bc01b3c4774bd2195 100644 (file)
--- a/opendaylight/md-sal/cds-access-client/src/main/java/org/opendaylight/controller/cluster/access/client/ProgressTracker.java
+++ b/opendaylight/md-sal/cds-access-client/src/main/java/org/opendaylight/controller/cluster/access/client/ProgressTracker.java
@@ -17,30 +17,33 @@ import org.slf4j.LoggerFactory;
  * Base class for tracking throughput and computing delays when processing stream of tasks.
  *
  * <p>The idea is to improve throughput in a typical request-response scenario.
- * A "frontend" is sending requests towards "backend", backend is sending responses back to fronted.
- * Both frontend and backend may be realized by multiple Java threads,
- * so there may be multiple requests not yet responded to.
- * In terms of taks processing, frontend is "opening" tasks and backend is "closing" them.
+ * Multiple "user" threads are submitting requests to a "frontend". The frontend does some
+ * pre-processing and then sends requests to (usually one) "backend". The backend does the main work
+ * and replies to the frontend, which reports to the the corresponding user.
+ * In terms of task processing, user threads are "opening" tasks and frontend is "closing" them.
  * Latency of the backend may fluctuate wildly. To avoid backend running out of open tasks,
- * there should be a queue of requests frontend can add to.
+ * frontend should maintain a queue of requests for users to submit tasks to.
  * In order to avoid excessive memory consumption, there should be a back-pressure mechanism
- * which blocks the frontend threads for appropriate durations.
- * Frontend can tolerate moderately delayed responses, but it only tolerates small block times.
+ * which blocks the user (submit) threads for appropriate durations.
+ * Users can tolerate moderately delayed responses, but they only tolerate small block (submit)
+ * times.
  *
  * <p>An ideal back-pressure algorithm would keep the queue reasonably full,
- * while fairly delaying the frontend threads. In other words, backend idle time should be low,
- * as well as frontend block time dispersion
+ * while fairly delaying the user threads. In other words, backend idle time should be low,
+ * as well as user block time dispersion
  * (as opposed to block time average, which is dictated by overall performance).
  *
  * <p>In order for an algorithm to compute reasonable wait times,
  * various inputs can be useful, mostly related to timing of various stages of task processing.
- * Methods of this class assume "enqueue and wait" usage.
- * The delay computation is pessimistic, it expects each participating thread to enqueue another task
- * as soon as its delay time allows.
+ * Methods of this class assume "enqueue and wait" usage, submit thread is supposed to block itself
+ * when asked to. The delay computation is pessimistic, it expects each participating thread
+ * to enqueue another task as soon as its delay time allows.
  *
- * <p>This class is not thread safe, the callers are responsible for guarding against conflicting access.
- * Time is measured in ticks (nanos), methods never look at current time, relying on {@code now} argument instead.
- * This means the sequence of {$code now} argument values is expected to be non-decreasing.
+ * <p>This class is to be used by single frontend. This class is not thread safe,
+ * the frontend is responsible for guarding against conflicting access.
+ * Time is measured in ticks (nanoseconds), methods never look at current time,
+ * relying on {@code now} argument where appropriate.
+ * This means the sequence of {@code now} argument values is expected to be non-decreasing.
  *
  * <p>Input data used for tracking is tightly coupled with TransitQueue#recordCompletion arguments.
  *