14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import jdk.internal.vm.annotation.IntrinsicCandidate;
29
30 /**
31 * Class {@code Object} is the root of the class hierarchy.
32 * Every class has {@code Object} as a superclass. All objects,
33 * including arrays, implement the methods of this class.
34 *
35 * @see java.lang.Class
36 * @since 1.0
37 */
38 public class Object {
39
40 /**
41 * Constructs a new object.
42 */
43 @IntrinsicCandidate
44 public Object() {}
45
46 /**
47 * Returns the runtime class of this {@code Object}. The returned
48 * {@code Class} object is the object that is locked by {@code
49 * static synchronized} methods of the represented class.
50 *
51 * <p><b>The actual result type is {@code Class<? extends |X|>}
52 * where {@code |X|} is the erasure of the static type of the
53 * expression on which {@code getClass} is called.</b> For
278 * <p>
279 * The awakened thread will not be able to proceed until the current
280 * thread relinquishes the lock on this object. The awakened thread will
281 * compete in the usual manner with any other threads that might be
282 * actively competing to synchronize on this object; for example, the
283 * awakened thread enjoys no reliable privilege or disadvantage in being
284 * the next thread to lock this object.
285 * <p>
286 * This method should only be called by a thread that is the owner
287 * of this object's monitor. A thread becomes the owner of the
288 * object's monitor in one of three ways:
289 * <ul>
290 * <li>By executing a synchronized instance method of that object.
291 * <li>By executing the body of a {@code synchronized} statement
292 * that synchronizes on the object.
293 * <li>For objects of type {@code Class,} by executing a
294 * static synchronized method of that class.
295 * </ul>
296 * <p>
297 * Only one thread at a time can own an object's monitor.
298 *
299 * @throws IllegalMonitorStateException if the current thread is not
300 * the owner of this object's monitor.
301 * @see java.lang.Object#notifyAll()
302 * @see java.lang.Object#wait()
303 */
304 @IntrinsicCandidate
305 public final native void notify();
306
307 /**
308 * Wakes up all threads that are waiting on this object's monitor. A
309 * thread waits on an object's monitor by calling one of the
310 * {@code wait} methods.
311 * <p>
312 * The awakened threads will not be able to proceed until the current
313 * thread relinquishes the lock on this object. The awakened threads
314 * will compete in the usual manner with any other threads that might
315 * be actively competing to synchronize on this object; for example,
316 * the awakened threads enjoy no reliable privilege or disadvantage in
317 * being the next thread to lock this object.
318 * <p>
319 * This method should only be called by a thread that is the owner
320 * of this object's monitor. See the {@code notify} method for a
321 * description of the ways in which a thread can become the owner of
322 * a monitor.
323 *
324 * @throws IllegalMonitorStateException if the current thread is not
325 * the owner of this object's monitor.
326 * @see java.lang.Object#notify()
327 * @see java.lang.Object#wait()
328 */
329 @IntrinsicCandidate
330 public final native void notifyAll();
331
332 /**
333 * Causes the current thread to wait until it is awakened, typically
334 * by being <em>notified</em> or <em>interrupted</em>.
335 * <p>
336 * In all respects, this method behaves as if {@code wait(0L, 0)}
337 * had been called. See the specification of the {@link #wait(long, int)} method
338 * for details.
339 *
340 * @throws IllegalMonitorStateException if the current thread is not
341 * the owner of the object's monitor
342 * @throws InterruptedException if any thread interrupted the current thread before or
343 * while the current thread was waiting. The <em>interrupted status</em> of the
344 * current thread is cleared when this exception is thrown.
345 * @see #notify()
346 * @see #notifyAll()
347 * @see #wait(long)
348 * @see #wait(long, int)
349 */
350 public final void wait() throws InterruptedException {
351 wait(0L);
352 }
353
354 /**
355 * Causes the current thread to wait until it is awakened, typically
356 * by being <em>notified</em> or <em>interrupted</em>, or until a
357 * certain amount of real time has elapsed.
358 * <p>
359 * In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
360 * had been called. See the specification of the {@link #wait(long, int)} method
361 * for details.
362 *
363 * @param timeoutMillis the maximum time to wait, in milliseconds
364 * @throws IllegalArgumentException if {@code timeoutMillis} is negative
365 * @throws IllegalMonitorStateException if the current thread is not
366 * the owner of the object's monitor
367 * @throws InterruptedException if any thread interrupted the current thread before or
368 * while the current thread was waiting. The <em>interrupted status</em> of the
369 * current thread is cleared when this exception is thrown.
370 * @see #notify()
371 * @see #notifyAll()
372 * @see #wait()
373 * @see #wait(long, int)
374 */
375 public final void wait(long timeoutMillis) throws InterruptedException {
376 if (timeoutMillis < 0) {
377 throw new IllegalArgumentException("timeout value is negative");
378 }
379
380 if (Thread.currentThread() instanceof VirtualThread vthread) {
381 try {
382 wait0(timeoutMillis);
383 } catch (InterruptedException e) {
384 // virtual thread's interrupt status needs to be cleared
385 vthread.getAndClearInterrupt();
386 throw e;
456 * this exception is thrown. This exception is not thrown until the lock status of
457 * this object has been restored as described above.
458 *
459 * @apiNote
460 * The recommended approach to waiting is to check the condition being awaited in
461 * a {@code while} loop around the call to {@code wait}, as shown in the example
462 * below. Among other things, this approach avoids problems that can be caused
463 * by spurious wakeups.
464 *
465 * {@snippet lang=java :
466 * synchronized (obj) {
467 * while ( <condition does not hold and timeout not exceeded> ) {
468 * long timeoutMillis = ... ; // recompute timeout values
469 * int nanos = ... ;
470 * obj.wait(timeoutMillis, nanos);
471 * }
472 * ... // Perform action appropriate to condition or timeout
473 * }
474 * }
475 *
476 * @param timeoutMillis the maximum time to wait, in milliseconds
477 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
478 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
479 * or if the value of {@code nanos} is out of range
480 * @throws IllegalMonitorStateException if the current thread is not
481 * the owner of the object's monitor
482 * @throws InterruptedException if any thread interrupted the current thread before or
483 * while the current thread was waiting. The <em>interrupted status</em> of the
484 * current thread is cleared when this exception is thrown.
485 * @see #notify()
486 * @see #notifyAll()
487 * @see #wait()
488 * @see #wait(long)
489 */
490 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
491 if (timeoutMillis < 0) {
492 throw new IllegalArgumentException("timeoutMillis value is negative");
493 }
494
495 if (nanos < 0 || nanos > 999999) {
496 throw new IllegalArgumentException(
497 "nanosecond timeout value out of range");
498 }
499
500 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
501 timeoutMillis++;
|
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import jdk.internal.vm.annotation.IntrinsicCandidate;
29
30 /**
31 * Class {@code Object} is the root of the class hierarchy.
32 * Every class has {@code Object} as a superclass. All objects,
33 * including arrays, implement the methods of this class.
34 * <p>
35 * Subclasses of {@code java.lang.Object} can be either an {@linkplain Class#isIdentity identity class}
36 * or a {@linkplain Class#isValue value class}.
37 * See {@jls The Java Language Specification 8.1.1.5 Value Classes}.
38 *
39 * @see java.lang.Class
40 * @since 1.0
41 */
42 public class Object {
43
44 /**
45 * Constructs a new object.
46 */
47 @IntrinsicCandidate
48 public Object() {}
49
50 /**
51 * Returns the runtime class of this {@code Object}. The returned
52 * {@code Class} object is the object that is locked by {@code
53 * static synchronized} methods of the represented class.
54 *
55 * <p><b>The actual result type is {@code Class<? extends |X|>}
56 * where {@code |X|} is the erasure of the static type of the
57 * expression on which {@code getClass} is called.</b> For
282 * <p>
283 * The awakened thread will not be able to proceed until the current
284 * thread relinquishes the lock on this object. The awakened thread will
285 * compete in the usual manner with any other threads that might be
286 * actively competing to synchronize on this object; for example, the
287 * awakened thread enjoys no reliable privilege or disadvantage in being
288 * the next thread to lock this object.
289 * <p>
290 * This method should only be called by a thread that is the owner
291 * of this object's monitor. A thread becomes the owner of the
292 * object's monitor in one of three ways:
293 * <ul>
294 * <li>By executing a synchronized instance method of that object.
295 * <li>By executing the body of a {@code synchronized} statement
296 * that synchronizes on the object.
297 * <li>For objects of type {@code Class,} by executing a
298 * static synchronized method of that class.
299 * </ul>
300 * <p>
301 * Only one thread at a time can own an object's monitor.
302 * <div class="preview-block">
303 * <div class="preview-comment">
304 * If this object is a {@linkplain Class#isValue() value object},
305 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
306 * </div>
307 * </div>
308 *
309 * @throws IllegalMonitorStateException if the current thread is not
310 * the owner of this object's monitor or
311 * if this object is a {@linkplain Class#isValue() value object}.
312 * @see java.lang.Object#notifyAll()
313 * @see java.lang.Object#wait()
314 */
315 @IntrinsicCandidate
316 public final native void notify();
317
318 /**
319 * Wakes up all threads that are waiting on this object's monitor. A
320 * thread waits on an object's monitor by calling one of the
321 * {@code wait} methods.
322 * <p>
323 * The awakened threads will not be able to proceed until the current
324 * thread relinquishes the lock on this object. The awakened threads
325 * will compete in the usual manner with any other threads that might
326 * be actively competing to synchronize on this object; for example,
327 * the awakened threads enjoy no reliable privilege or disadvantage in
328 * being the next thread to lock this object.
329 * <p>
330 * This method should only be called by a thread that is the owner
331 * of this object's monitor. See the {@code notify} method for a
332 * description of the ways in which a thread can become the owner of
333 * a monitor.
334 *
335 * <div class="preview-block">
336 * <div class="preview-comment">
337 * If this object is a {@linkplain Class#isValue() value object},
338 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
339 * </div>
340 * </div>
341 *
342 * @throws IllegalMonitorStateException if the current thread is not
343 * the owner of this object's monitor or
344 * if this object is a {@linkplain Class#isValue() value object}.
345 * @see java.lang.Object#notify()
346 * @see java.lang.Object#wait()
347 */
348 @IntrinsicCandidate
349 public final native void notifyAll();
350
351 /**
352 * Causes the current thread to wait until it is awakened, typically
353 * by being <em>notified</em> or <em>interrupted</em>.
354 * <p>
355 * In all respects, this method behaves as if {@code wait(0L, 0)}
356 * had been called. See the specification of the {@link #wait(long, int)} method
357 * for details.
358 *
359 * <div class="preview-block">
360 * <div class="preview-comment">
361 * If this object is a {@linkplain Class#isValue() value object},
362 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
363 * </div>
364 * </div>
365 *
366 * @throws IllegalMonitorStateException if the current thread is not
367 * the owner of the object's monitor or
368 * if this object is a {@linkplain Class#isValue() value object}.
369 * @throws InterruptedException if any thread interrupted the current thread before or
370 * while the current thread was waiting. The <em>interrupted status</em> of the
371 * current thread is cleared when this exception is thrown.
372 * @see #notify()
373 * @see #notifyAll()
374 * @see #wait(long)
375 * @see #wait(long, int)
376 */
377 public final void wait() throws InterruptedException {
378 wait(0L);
379 }
380
381 /**
382 * Causes the current thread to wait until it is awakened, typically
383 * by being <em>notified</em> or <em>interrupted</em>, or until a
384 * certain amount of real time has elapsed.
385 * <p>
386 * In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
387 * had been called. See the specification of the {@link #wait(long, int)} method
388 * for details.
389 *
390 * <div class="preview-block">
391 * <div class="preview-comment">
392 * If this object is a {@linkplain Class#isValue() value object},
393 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
394 * </div>
395 * </div>
396 *
397 * @param timeoutMillis the maximum time to wait, in milliseconds
398 * @throws IllegalArgumentException if {@code timeoutMillis} is negative
399 * @throws IllegalMonitorStateException if the current thread is not
400 * the owner of the object's monitor or
401 * if this object is a {@linkplain Class#isValue() value object}.
402 * @throws InterruptedException if any thread interrupted the current thread before or
403 * while the current thread was waiting. The <em>interrupted status</em> of the
404 * current thread is cleared when this exception is thrown.
405 * @see #notify()
406 * @see #notifyAll()
407 * @see #wait()
408 * @see #wait(long, int)
409 */
410 public final void wait(long timeoutMillis) throws InterruptedException {
411 if (timeoutMillis < 0) {
412 throw new IllegalArgumentException("timeout value is negative");
413 }
414
415 if (Thread.currentThread() instanceof VirtualThread vthread) {
416 try {
417 wait0(timeoutMillis);
418 } catch (InterruptedException e) {
419 // virtual thread's interrupt status needs to be cleared
420 vthread.getAndClearInterrupt();
421 throw e;
491 * this exception is thrown. This exception is not thrown until the lock status of
492 * this object has been restored as described above.
493 *
494 * @apiNote
495 * The recommended approach to waiting is to check the condition being awaited in
496 * a {@code while} loop around the call to {@code wait}, as shown in the example
497 * below. Among other things, this approach avoids problems that can be caused
498 * by spurious wakeups.
499 *
500 * {@snippet lang=java :
501 * synchronized (obj) {
502 * while ( <condition does not hold and timeout not exceeded> ) {
503 * long timeoutMillis = ... ; // recompute timeout values
504 * int nanos = ... ;
505 * obj.wait(timeoutMillis, nanos);
506 * }
507 * ... // Perform action appropriate to condition or timeout
508 * }
509 * }
510 *
511 * <div class="preview-block">
512 * <div class="preview-comment">
513 * If this object is a {@linkplain Class#isValue() value object},
514 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
515 * </div>
516 * </div>
517 * @param timeoutMillis the maximum time to wait, in milliseconds
518 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
519 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
520 * or if the value of {@code nanos} is out of range
521 * @throws IllegalMonitorStateException if the current thread is not
522 * the owner of the object's monitor or
523 * if this object is a {@linkplain Class#isValue() value object}.
524 * @throws InterruptedException if any thread interrupted the current thread before or
525 * while the current thread was waiting. The <em>interrupted status</em> of the
526 * current thread is cleared when this exception is thrown.
527 * @see #notify()
528 * @see #notifyAll()
529 * @see #wait()
530 * @see #wait(long)
531 */
532 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
533 if (timeoutMillis < 0) {
534 throw new IllegalArgumentException("timeoutMillis value is negative");
535 }
536
537 if (nanos < 0 || nanos > 999999) {
538 throw new IllegalArgumentException(
539 "nanosecond timeout value out of range");
540 }
541
542 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
543 timeoutMillis++;
|