@@ -200,6 +200,10 @@ Time
200200 ] ( #time-going-backward )
201201 - [ Units for a time variable are identified in the variable's name or via ` TimeUnit ` ?] ( #time-units )
202202 - [ Negative timeouts and delays are treated as zeros?] ( #treat-negative-timeout-as-zero )
203+ - [ Tasks connected to system time or UTC time are * not* scheduled using
204+ ` ScheduledThreadPoolExecutor ` ?] ( #external-interaction-schedule )
205+ - [ Human and external interactions on consumer devices are * not* scheduled using
206+ ` ScheduledThreadPoolExecutor ` ?] ( #user-interaction-schedule )
203207
204208` ThreadLocal `
205209 - [ ` ThreadLocal ` can be ` static final ` ?] ( #tl-static-final )
@@ -1349,6 +1353,10 @@ context executor may not be well-suited for blocking calls such as `Thread.sleep
13491353This item equally applies to scheduling one-shot and recurrent delayed actions, there are methods
13501354for both scenarios in ` ScheduledExecutorService ` .
13511355
1356+ Be cautious, however, about scheduling tasks with affinity to system time or UTC time (e. g.
1357+ beginning of each hour) using ` ScheduledThreadPoolExecutor ` : it can experience [ unbounded clock
1358+ drift] ( #external-interaction-schedule ) .
1359+ 13521360### Parallel Streams
13531361
13541362<a name =" justify-parallel-stream-use " ></a >
@@ -1537,6 +1545,37 @@ parameter next to a "timeout" parameter. This is the preferred option for public
15371545treat negative arguments as zeros?** This is to obey the principle of least astonishment because all
15381546timed blocking methods in classes from ` java.util.concurrent.* ` follow this convention.
15391547
1548+ <a name =" external-interaction-schedule " ></a >
1549+ [ #] ( #external-interaction-schedule ) Tm.5. ** Tasks that should happen at a certain system time, UTC
1550+ time, or wall-clock time far in the future, or run periodically with a cadence expressed in terms of
1551+ system/UTC/wall-clock time (rather than internal machines's CPU time) are * not* scheduled with
1552+ ` ScheduledThreadPoolExecutor ` ?** ` ScheduledThreadPoolExecutor ` (this class is also behind all
1553+ factory methods in ` Executors ` which return a ` ScheduledExecutorService ` ) uses ` System.nanoTime() `
1554+ for timing intervals. [ ` nanoTime() ` can drift against the system time and the UTC time.] (
1555+ https://medium.com/@leventov/cronscheduler-a-reliable-java-scheduler-for-external-interactions-cb7ce4a4f2cd )
1556+ 1557+ [ ` CronScheduler ` ] ( https://github.com/TimeAndSpaceIO/CronScheduler ) is a scheduling class designed
1558+ to be proof against unbounded clock drift relative to UTC or system time for both one-shot or
1559+ periodic tasks. See more detailed recommendations on [ choosing between
1560+ ` ScheduledThreadPoolExecutor ` and ` CronScheduler ` ] (
1561+ https://medium.com/@leventov/cronscheduler-a-reliable-java-scheduler-for-external-interactions-cb7ce4a4f2cd#4926 ).
1562+ On Android, use [ Android-specific APIs] (
1563+ https://android.jlelse.eu/schedule-tasks-and-jobs-intelligently-in-android-e0b0d9201777 ).
1564+ 1565+ <a name =" user-interaction-schedule " ></a >
1566+ [ #] ( #user-interaction-schedule ) Tm.6. On consumer devices (PCs, laptops, tables, phones),
1567+ ** ` ScheduledThreadPoolExecutor ` (or ` Timer ` ) is * not* used for human interaction tasks or
1568+ interactions between the device and a remote service?** Examples of human interaction tasks are
1569+ alarms, notifications, timers, or task management. Examples of interactions between user's device
1570+ and remote services are checking for new e-mails or messages, widget updates, or software updates.
1571+ The reason for this is that [ neither ` ScheduledThreadPoolExecutor ` nor ` Timer ` account for machine
1572+ suspension] (
1573+ https://medium.com/@leventov/cronscheduler-a-reliable-java-scheduler-for-external-interactions-cb7ce4a4f2cd#dcfe )
1574+ (such as sleep or hibernation mode). On Android, use [ Android-specific APIs] (
1575+ https://android.jlelse.eu/schedule-tasks-and-jobs-intelligently-in-android-e0b0d9201777 ) instead.
1576+ Consider [ CronScheduler] ( https://github.com/TimeAndSpaceIO/CronScheduler ) as a replacement for
1577+ ` ScheduledThreadPoolExecutor ` in these cases for end-user JVM apps.
1578+ 15401579### ` ThreadLocal `
15411580
15421581<a name =" tl-static-final " ></a >
0 commit comments