archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
Reviewed-by: naoto, jpai, rriggs
This commit is contained in:
Justin Lu 2023-11-07 21:33:33 +00:00
parent a290256bbf
commit cc4b0d9217
1 changed files with 19 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

33
src/java.base/share/classes/java/util/Timer.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -63,7 +63,7 @@ import jdk.internal.ref.CleanerFactory;
* <p>This class does <i>not</i> offer real-time guarantees: it schedules
* tasks using the {@code Object.wait(long)} method.
*
* <p>Java 5.0 introduced the {@code java.util.concurrent} package and
* @apiNote Java 5.0 introduced the {@code java.util.concurrent} package and
* one of the concurrency utilities therein is the {@link
* java.util.concurrent.ScheduledThreadPoolExecutor
* ScheduledThreadPoolExecutor} which is a thread pool for repeatedly
@ -74,13 +74,11 @@ import jdk.internal.ref.CleanerFactory;
* implement {@code Runnable}). Configuring {@code
* ScheduledThreadPoolExecutor} with one thread makes it equivalent to
* {@code Timer}.
*
* <p>Implementation note: This class scales to large numbers of concurrently
* @implNote This class scales to large numbers of concurrently
* scheduled tasks (thousands should present no problem). Internally,
* it uses a binary heap to represent its task queue, so the cost to schedule
* a task is O(log n), where n is the number of concurrently scheduled tasks.
*
* <p>Implementation note: All constructors start a timer thread.
* <p> All constructors start a timer thread.
*
* @author Josh Bloch
* @see TimerTask
@ -424,8 +422,12 @@ public class Timer {
}
/**
* Terminates this timer, discarding any currently scheduled tasks.
* Does not interfere with a currently executing task (if it exists).
* Terminates this timer, <i>discarding</i> any currently scheduled tasks.
* It should be noted that this method does not <i>cancel</i> the scheduled
* tasks. For a task to be considered cancelled, the task itself should
* invoke {@link TimerTask#cancel()}.
*
* <p>This method does not interfere with a currently executing task (if it exists).
* Once a timer has been terminated, its execution thread terminates
* gracefully, and no more tasks may be scheduled on it.
*
@ -436,6 +438,7 @@ public class Timer {
*
* <p>This method may be called repeatedly; the second and subsequent
* calls have no effect.
* @see TimerTask#cancel()
*/
public void cancel() {
synchronized(queue) {
@ -445,23 +448,25 @@ public class Timer {
}
/**
* Removes all cancelled tasks from this timer's task queue. <i>Calling
* this method has no effect on the behavior of the timer</i>, but
* eliminates the references to the cancelled tasks from the queue.
* Removes all <i>cancelled</i> tasks from this timer's task queue.
* <i>Calling this method has no effect on the behavior of the timer</i>,
* but eliminates the references to the cancelled tasks from the queue.
* If there are no external references to these tasks, they become
* eligible for garbage collection.
*
* <p>Most programs will have no need to call this method.
* It is designed for use by the rare application that cancels a large
* number of tasks. Calling this method trades time for space: the
* runtime of the method may be proportional to n + c log n, where n
* is the number of tasks in the queue and c is the number of cancelled
* tasks.
* runtime of the method may be proportional to {@code n + c log n}, where
* {@code n} is the number of tasks in the queue and {@code c} is the number
* of cancelled tasks.
*
* <p>Note that it is permissible to call this method from within
* a task scheduled on this timer.
*
* @return the number of tasks removed from the queue.
* @see #cancel()
* @see TimerTask#cancel()
* @since 1.5
*/
public int purge() {