Integrated: 8319378: Spec for j.util.Timer::purge and j.util.Timer::cancel could be improved

[Justin Lu]

On Fri, 3 Nov 2023 20:40:11 GMT, Justin Lu <jlu at openjdk.org> wrote:

> Please review this PR which clarifies the definition of a _cancelled_ task in _j.util.Timer::purge_ and _j.util.Timer::cancel_.
> 
> Timer::purge claims that its return value is the number of tasks in the queue that were cancelled. This can be misleading, as a user can call Timer::cancel, thinking the rest of the tasks in the queue will be canceled (which should be the return value of Timer::purge).
> 
> In actuality, Timer::cancel _discards_ all of the tasks in the queue. For a task to have been _cancelled_, the task itself must have called TimerTask::cancel. 
> 
> This change emphasizes the difference between _discarding_ and _cancelling_ a task.
> Additionally, this change also includes a drive-by update to use an _apiNote_ and _implNote_ tag in the class description.

This pull request has now been integrated.

Changeset: cc4b0d92
Author:    Justin Lu <jlu at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/cc4b0d9217ed27a9555dc82f0a4247bf9b703f2b
Stats:     21 lines in 1 file changed: 7 ins; 2 del; 12 mod

8319378: Spec for j.util.Timer::purge and j.util.Timer::cancel could be improved

Reviewed-by: naoto, jpai, rriggs

-------------

PR: https://git.openjdk.org/jdk/pull/16503