yifan-c commented on code in PR #200:
URL: https://github.com/apache/cassandra-sidecar/pull/200#discussion_r1988436114
##########
CONTRIBUTING.md:
##########
@@ -128,57 +159,94 @@ The `service` worker pool has the name
`sidecar-worker-pool`.
The `internal` worker pool has the name `sidecar-internal-worker-pool`.
-### <a href="timers"></a>One-shot Timers and Periodic Timers
+### <a name="timers"></a>One-shot Timers and Periodic Timers
Use vertx APIs to set one-shot timers and periodic timers. If you need to
execute a one-time operation in the future,
or if you need to run periodic operations within vertx, an API is available.
These timers utilize vertx provisioned
-threads that are managed internal by vertx. For example
+threads that are managed internal by vertx. For example, the below code
snippet runs `action()` after `delayMillis`.
```java
-logger.debug("Retrying streaming after {} millis", millis);
-executorPools.service().setTimer(millis, t -> acquireAndSend(context,
filename, fileLength, range, startTime));
+executorPools.service().setTimer(delayMillis, timerId -> action());
```
-### <a href="guice"></a>Dependency Injection
+Similarly, a simple periodic task can be schedule with the following code. The
`action()` is scheduled to run after
+the `initialDelayMillis` and repeat every `delayMillis`.
-The Apache Cassandra Sidecar project uses Guice for handling the object
interdependency. When a class encapsulates
-some functionality that is then used by a different class in the system, we
use Guice for dependency injection.
+```java
+executorPools.internal().setPeriodic(initialDelayMillis, delayMillis, timerId
-> action());
+```
+Note that such periodic task is triggered whenever the scheduled time has
arrived, consider the equivalent
+`ScheduledExecutorService#scheduleAtFixedRate`. It is possible to have
concurrent runs, depending on the delay parameters.
+It might not be the desired scheduling behavior for the use case. If serial
execution sequence is wanted, check out the
+scheduling mechanism described in [Advanced periodic task
scheduling](#advanced-periodic-scheduling)
-When a different implementation can be provided in the future, prefer using an
interface and a default implementation
-that can be later switched transparently without affecting the classes that
depend on it.
+#### <a name="advanced-periodic-scheduling">Advanced periodic task scheduling
-Prefer creating concrete classes over utility methods. The concrete classes
can be managed as a
-[Singleton](https://en.wikipedia.org/wiki/Singleton_pattern) if they do not
have external dependencies that might
-change their behavior based on the configuration.
+`PeriodicTaskExecutor` provides the scheduling behavior that is similar to the
hybrid of `ScheduledExecutorService#scheduleAtFixedRate`
+and `ScheduledExecutorService#scheduleAtFixedDelay`. The unit of execution is
`PeriodicTask`.
-Here's an example of a class being managed by Guice.
+A `PeriodicTask` is guaranteed to be executed in serial by
`PeriodicTaskExecutor`, as if such task is executed from
+a single thread. Memory consistency is ensured, i.e. the effect of write from
the last run is visible to the current run.
+The interval between the consecutive runs is adjusted based on the duration
taken by the last run. This way, its behavior
Review Comment:
The duration is the time taken between task start and the promise is
completed. It is generally not advised to schedule async actions (during a task
execution) that do not take the `promise` into consideration. It can break the
memory consistency. On the other hand, if the `promise` is completed at the end
of the last async action, (which is the correct way), the duration is known.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
