1 /*
2 * Copyright (c) 1994, 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
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.AOTSafeClassInitializer;
29 import jdk.internal.vm.annotation.IntrinsicCandidate;
30
31 /**
32 * Class {@code Object} is the root of the class hierarchy.
33 * Every class has {@code Object} as a superclass. All objects,
34 * including arrays, implement the methods of this class.
35 *
36 * @see java.lang.Class
37 * @since 1.0
38 */
39 @AOTSafeClassInitializer // for hierarchy checks
40 public class Object {
41
42 /**
43 * Constructs a new object.
44 */
45 @IntrinsicCandidate
46 public Object() {}
47
48 /**
49 * Returns the runtime class of this {@code Object}. The returned
50 * {@code Class} object is the object that is locked by {@code
51 * static synchronized} methods of the represented class.
52 *
53 * <p><b>The actual result type is {@code Class<? extends |X|>}
54 * where {@code |X|} is the erasure of the static type of the
55 * expression on which {@code getClass} is called.</b> For
280 * <p>
281 * The awakened thread will not be able to proceed until the current
282 * thread relinquishes the lock on this object. The awakened thread will
283 * compete in the usual manner with any other threads that might be
284 * actively competing to synchronize on this object; for example, the
285 * awakened thread enjoys no reliable privilege or disadvantage in being
286 * the next thread to lock this object.
287 * <p>
288 * This method should only be called by a thread that is the owner
289 * of this object's monitor. A thread becomes the owner of the
290 * object's monitor in one of three ways:
291 * <ul>
292 * <li>By executing a synchronized instance method of that object.
293 * <li>By executing the body of a {@code synchronized} statement
294 * that synchronizes on the object.
295 * <li>For objects of type {@code Class,} by executing a
296 * static synchronized method of that class.
297 * </ul>
298 * <p>
299 * Only one thread at a time can own an object's monitor.
300 *
301 * @throws IllegalMonitorStateException if the current thread is not
302 * the owner of this object's monitor.
303 * @see java.lang.Object#notifyAll()
304 * @see java.lang.Object#wait()
305 */
306 @IntrinsicCandidate
307 public final native void notify();
308
309 /**
310 * Wakes up all threads that are waiting on this object's monitor. A
311 * thread waits on an object's monitor by calling one of the
312 * {@code wait} methods.
313 * <p>
314 * The awakened threads will not be able to proceed until the current
315 * thread relinquishes the lock on this object. The awakened threads
316 * will compete in the usual manner with any other threads that might
317 * be actively competing to synchronize on this object; for example,
318 * the awakened threads enjoy no reliable privilege or disadvantage in
319 * being the next thread to lock this object.
320 * <p>
321 * This method should only be called by a thread that is the owner
322 * of this object's monitor. See the {@code notify} method for a
323 * description of the ways in which a thread can become the owner of
324 * a monitor.
325 *
326 * @throws IllegalMonitorStateException if the current thread is not
327 * the owner of this object's monitor.
328 * @see java.lang.Object#notify()
329 * @see java.lang.Object#wait()
330 */
331 @IntrinsicCandidate
332 public final native void notifyAll();
333
334 /**
335 * Causes the current thread to wait until it is awakened, typically
336 * by being <em>notified</em> or <em>interrupted</em>.
337 * <p>
338 * In all respects, this method behaves as if {@code wait(0L, 0)}
339 * had been called. See the specification of the {@link #wait(long, int)} method
340 * for details.
341 *
342 * @throws IllegalMonitorStateException if the current thread is not
343 * the owner of the object's monitor
344 * @throws InterruptedException if any thread interrupted the current thread before or
345 * while the current thread was waiting. The <em>interrupted status</em> of the
346 * current thread is cleared when this exception is thrown.
347 * @see #notify()
348 * @see #notifyAll()
349 * @see #wait(long)
350 * @see #wait(long, int)
351 */
352 public final void wait() throws InterruptedException {
353 wait(0L);
354 }
355
356 /**
357 * Causes the current thread to wait until it is awakened, typically
358 * by being <em>notified</em> or <em>interrupted</em>, or until a
359 * certain amount of real time has elapsed.
360 * <p>
361 * In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
362 * had been called. See the specification of the {@link #wait(long, int)} method
363 * for details.
364 *
365 * @param timeoutMillis the maximum time to wait, in milliseconds
366 * @throws IllegalArgumentException if {@code timeoutMillis} is negative
367 * @throws IllegalMonitorStateException if the current thread is not
368 * the owner of the object's monitor
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()
375 * @see #wait(long, int)
376 */
377 public final void wait(long timeoutMillis) throws InterruptedException {
378 if (timeoutMillis < 0) {
379 throw new IllegalArgumentException("timeout value is negative");
380 }
381
382 if (Thread.currentThread() instanceof VirtualThread vthread) {
383 try {
384 wait0(timeoutMillis);
385 } catch (InterruptedException e) {
386 // virtual thread's interrupted status needs to be cleared
387 vthread.getAndClearInterrupt();
388 throw e;
441 * was invoked.
442 * <p>
443 * A thread can wake up without being notified, interrupted, or timing out, a
444 * so-called <em>spurious wakeup</em>. While this will rarely occur in practice,
445 * applications must guard against it by testing for the condition that should
446 * have caused the thread to be awakened, and continuing to wait if the condition
447 * is not satisfied. See the example below.
448 * <p>
449 * For more information on this topic, see section 14.2,
450 * "Condition Queues," in Brian Goetz and others' <cite>Java Concurrency
451 * in Practice</cite> (Addison-Wesley, 2006) or Item 81 in Joshua
452 * Bloch's <cite>Effective Java, Third Edition</cite> (Addison-Wesley,
453 * 2018).
454 * <p>
455 * If the current thread is {@linkplain java.lang.Thread#interrupt() interrupted}
456 * by any thread before or while it is waiting, then an {@code InterruptedException}
457 * is thrown. The <em>interrupted status</em> of the current thread is cleared when
458 * this exception is thrown. This exception is not thrown until the lock status of
459 * this object has been restored as described above.
460 *
461 * @apiNote
462 * The recommended approach to waiting is to check the condition being awaited in
463 * a {@code while} loop around the call to {@code wait}, as shown in the example
464 * below. Among other things, this approach avoids problems that can be caused
465 * by spurious wakeups.
466 *
467 * {@snippet lang=java :
468 * synchronized (obj) {
469 * while ( <condition does not hold and timeout not exceeded> ) {
470 * long timeoutMillis = ... ; // recompute timeout values
471 * int nanos = ... ;
472 * obj.wait(timeoutMillis, nanos);
473 * }
474 * ... // Perform action appropriate to condition or timeout
475 * }
476 * }
477 *
478 * @param timeoutMillis the maximum time to wait, in milliseconds
479 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
480 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
481 * or if the value of {@code nanos} is out of range
482 * @throws IllegalMonitorStateException if the current thread is not
483 * the owner of the object's monitor
484 * @throws InterruptedException if any thread interrupted the current thread before or
485 * while the current thread was waiting. The <em>interrupted status</em> of the
486 * current thread is cleared when this exception is thrown.
487 * @see #notify()
488 * @see #notifyAll()
489 * @see #wait()
490 * @see #wait(long)
491 */
492 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
493 if (timeoutMillis < 0) {
494 throw new IllegalArgumentException("timeoutMillis value is negative");
495 }
496
497 if (nanos < 0 || nanos > 999999) {
498 throw new IllegalArgumentException(
499 "nanosecond timeout value out of range");
500 }
501
502 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
503 timeoutMillis++;
540 * invoke the {@code finalize} method for any given object. It is
541 * guaranteed, however, that the thread that invokes finalize will not
542 * be holding any user-visible synchronization locks when finalize is
543 * invoked. If an uncaught exception is thrown by the finalize method,
544 * the exception is ignored and finalization of that object terminates.
545 * <p>
546 * After the {@code finalize} method has been invoked for an object, no
547 * further action is taken until the Java virtual machine has again
548 * determined that there is no longer any means by which this object can
549 * be accessed by any thread that has not yet died, including possible
550 * actions by other objects or classes which are ready to be finalized,
551 * at which point the object may be discarded.
552 * <p>
553 * The {@code finalize} method is never invoked more than once by a Java
554 * virtual machine for any given object.
555 * <p>
556 * Any exception thrown by the {@code finalize} method causes
557 * the finalization of this object to be halted, but is otherwise
558 * ignored.
559 *
560 * @apiNote
561 * Classes that embed non-heap resources have many options
562 * for cleanup of those resources. The class must ensure that the
563 * lifetime of each instance is longer than that of any resource it embeds.
564 * {@link java.lang.ref.Reference#reachabilityFence} can be used to ensure that
565 * objects remain reachable while resources embedded in the object are in use.
566 * <p>
567 * A subclass should avoid overriding the {@code finalize} method
568 * unless the subclass embeds non-heap resources that must be cleaned up
569 * before the instance is collected.
570 * Finalizer invocations are not automatically chained, unlike constructors.
571 * If a subclass overrides {@code finalize} it must invoke the superclass
572 * finalizer explicitly.
573 * To guard against exceptions prematurely terminating the finalize chain,
574 * the subclass should use a {@code try-finally} block to ensure
575 * {@code super.finalize()} is always invoked. For example,
576 * {@snippet lang="java":
577 * @Override
578 * protected void finalize() throws Throwable {
579 * try {
|
1 /*
2 * Copyright (c) 1994, 2026, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
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.AOTSafeClassInitializer;
29 import jdk.internal.vm.annotation.IntrinsicCandidate;
30
31 /**
32 * Class {@code Object} is the root of the class hierarchy.
33 * Every class has {@code Object} as a superclass. All objects,
34 * including arrays, implement the methods of this class.
35 *
36 * <div class="preview-block">
37 * <div class="preview-comment">
38 * When preview features are enabled, subclasses of {@code java.lang.Object} can be either
39 * identity classes or {@linkplain Class#isValue value classes}.
40 * See The Java Language Specification {@jls value-objects-8.1.1.5 Value Classes}.
41 * Use of value class instances for synchronization or with
42 * {@linkplain java.lang.ref.Reference object references} results in
43 * {@link IdentityException}.
44 * </div>
45 * </div>
46 *
47 * @see java.lang.Class
48 * @since 1.0
49 */
50 @AOTSafeClassInitializer // for hierarchy checks
51 public class Object {
52
53 /**
54 * Constructs a new object.
55 */
56 @IntrinsicCandidate
57 public Object() {}
58
59 /**
60 * Returns the runtime class of this {@code Object}. The returned
61 * {@code Class} object is the object that is locked by {@code
62 * static synchronized} methods of the represented class.
63 *
64 * <p><b>The actual result type is {@code Class<? extends |X|>}
65 * where {@code |X|} is the erasure of the static type of the
66 * expression on which {@code getClass} is called.</b> For
291 * <p>
292 * The awakened thread will not be able to proceed until the current
293 * thread relinquishes the lock on this object. The awakened thread will
294 * compete in the usual manner with any other threads that might be
295 * actively competing to synchronize on this object; for example, the
296 * awakened thread enjoys no reliable privilege or disadvantage in being
297 * the next thread to lock this object.
298 * <p>
299 * This method should only be called by a thread that is the owner
300 * of this object's monitor. A thread becomes the owner of the
301 * object's monitor in one of three ways:
302 * <ul>
303 * <li>By executing a synchronized instance method of that object.
304 * <li>By executing the body of a {@code synchronized} statement
305 * that synchronizes on the object.
306 * <li>For objects of type {@code Class,} by executing a
307 * static synchronized method of that class.
308 * </ul>
309 * <p>
310 * Only one thread at a time can own an object's monitor.
311 * <div class="preview-block">
312 * <div class="preview-comment">
313 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
314 * it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
315 * </div>
316 * </div>
317 *
318 * @throws IllegalMonitorStateException if the current thread is not
319 * the owner of this object's monitor or
320 * if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
321 * @see java.lang.Object#notifyAll()
322 * @see java.lang.Object#wait()
323 */
324 @IntrinsicCandidate
325 public final native void notify();
326
327 /**
328 * Wakes up all threads that are waiting on this object's monitor. A
329 * thread waits on an object's monitor by calling one of the
330 * {@code wait} methods.
331 * <p>
332 * The awakened threads will not be able to proceed until the current
333 * thread relinquishes the lock on this object. The awakened threads
334 * will compete in the usual manner with any other threads that might
335 * be actively competing to synchronize on this object; for example,
336 * the awakened threads enjoy no reliable privilege or disadvantage in
337 * being the next thread to lock this object.
338 * <p>
339 * This method should only be called by a thread that is the owner
340 * of this object's monitor. See the {@code notify} method for a
341 * description of the ways in which a thread can become the owner of
342 * a monitor.
343 *
344 * <div class="preview-block">
345 * <div class="preview-comment">
346 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
347 * it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
348 * </div>
349 * </div>
350 *
351 * @throws IllegalMonitorStateException if the current thread is not
352 * the owner of this object's monitor or
353 * if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
354 * @see java.lang.Object#notify()
355 * @see java.lang.Object#wait()
356 */
357 @IntrinsicCandidate
358 public final native void notifyAll();
359
360 /**
361 * Causes the current thread to wait until it is awakened, typically
362 * by being <em>notified</em> or <em>interrupted</em>.
363 * <p>
364 * In all respects, this method behaves as if {@code wait(0L, 0)}
365 * had been called. See the specification of the {@link #wait(long, int)} method
366 * for details.
367 *
368 * <div class="preview-block">
369 * <div class="preview-comment">
370 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
371 * it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
372 * </div>
373 * </div>
374 *
375 * @throws IllegalMonitorStateException if the current thread is not
376 * the owner of the object's monitor or
377 * if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
378 * @throws InterruptedException if any thread interrupted the current thread before or
379 * while the current thread was waiting. The <em>interrupted status</em> of the
380 * current thread is cleared when this exception is thrown.
381 * @see #notify()
382 * @see #notifyAll()
383 * @see #wait(long)
384 * @see #wait(long, int)
385 */
386 public final void wait() throws InterruptedException {
387 wait(0L);
388 }
389
390 /**
391 * Causes the current thread to wait until it is awakened, typically
392 * by being <em>notified</em> or <em>interrupted</em>, or until a
393 * certain amount of real time has elapsed.
394 * <p>
395 * In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
396 * had been called. See the specification of the {@link #wait(long, int)} method
397 * for details.
398 *
399 * <div class="preview-block">
400 * <div class="preview-comment">
401 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
402 * it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
403 * </div>
404 * </div>
405 *
406 * @param timeoutMillis the maximum time to wait, in milliseconds
407 * @throws IllegalArgumentException if {@code timeoutMillis} is negative
408 * @throws IllegalMonitorStateException if the current thread is not
409 * the owner of the object's monitor or
410 * if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
411 * @throws InterruptedException if any thread interrupted the current thread before or
412 * while the current thread was waiting. The <em>interrupted status</em> of the
413 * current thread is cleared when this exception is thrown.
414 * @see #notify()
415 * @see #notifyAll()
416 * @see #wait()
417 * @see #wait(long, int)
418 */
419 public final void wait(long timeoutMillis) throws InterruptedException {
420 if (timeoutMillis < 0) {
421 throw new IllegalArgumentException("timeout value is negative");
422 }
423
424 if (Thread.currentThread() instanceof VirtualThread vthread) {
425 try {
426 wait0(timeoutMillis);
427 } catch (InterruptedException e) {
428 // virtual thread's interrupted status needs to be cleared
429 vthread.getAndClearInterrupt();
430 throw e;
483 * was invoked.
484 * <p>
485 * A thread can wake up without being notified, interrupted, or timing out, a
486 * so-called <em>spurious wakeup</em>. While this will rarely occur in practice,
487 * applications must guard against it by testing for the condition that should
488 * have caused the thread to be awakened, and continuing to wait if the condition
489 * is not satisfied. See the example below.
490 * <p>
491 * For more information on this topic, see section 14.2,
492 * "Condition Queues," in Brian Goetz and others' <cite>Java Concurrency
493 * in Practice</cite> (Addison-Wesley, 2006) or Item 81 in Joshua
494 * Bloch's <cite>Effective Java, Third Edition</cite> (Addison-Wesley,
495 * 2018).
496 * <p>
497 * If the current thread is {@linkplain java.lang.Thread#interrupt() interrupted}
498 * by any thread before or while it is waiting, then an {@code InterruptedException}
499 * is thrown. The <em>interrupted status</em> of the current thread is cleared when
500 * this exception is thrown. This exception is not thrown until the lock status of
501 * this object has been restored as described above.
502 *
503 * <div class="preview-block">
504 * <div class="preview-comment">
505 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
506 * it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
507 * </div>
508 * </div>
509 *
510 * @apiNote
511 * The recommended approach to waiting is to check the condition being awaited in
512 * a {@code while} loop around the call to {@code wait}, as shown in the example
513 * below. Among other things, this approach avoids problems that can be caused
514 * by spurious wakeups.
515 *
516 * {@snippet lang=java :
517 * synchronized (obj) {
518 * while ( <condition does not hold and timeout not exceeded> ) {
519 * long timeoutMillis = ... ; // recompute timeout values
520 * int nanos = ... ;
521 * obj.wait(timeoutMillis, nanos);
522 * }
523 * ... // Perform action appropriate to condition or timeout
524 * }
525 * }
526 *
527 * @param timeoutMillis the maximum time to wait, in milliseconds
528 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
529 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
530 * or if the value of {@code nanos} is out of range
531 * @throws IllegalMonitorStateException if the current thread is not
532 * the owner of the object's monitor or
533 * if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
534 * @throws InterruptedException if any thread interrupted the current thread before or
535 * while the current thread was waiting. The <em>interrupted status</em> of the
536 * current thread is cleared when this exception is thrown.
537 * @see #notify()
538 * @see #notifyAll()
539 * @see #wait()
540 * @see #wait(long)
541 */
542 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
543 if (timeoutMillis < 0) {
544 throw new IllegalArgumentException("timeoutMillis value is negative");
545 }
546
547 if (nanos < 0 || nanos > 999999) {
548 throw new IllegalArgumentException(
549 "nanosecond timeout value out of range");
550 }
551
552 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
553 timeoutMillis++;
590 * invoke the {@code finalize} method for any given object. It is
591 * guaranteed, however, that the thread that invokes finalize will not
592 * be holding any user-visible synchronization locks when finalize is
593 * invoked. If an uncaught exception is thrown by the finalize method,
594 * the exception is ignored and finalization of that object terminates.
595 * <p>
596 * After the {@code finalize} method has been invoked for an object, no
597 * further action is taken until the Java virtual machine has again
598 * determined that there is no longer any means by which this object can
599 * be accessed by any thread that has not yet died, including possible
600 * actions by other objects or classes which are ready to be finalized,
601 * at which point the object may be discarded.
602 * <p>
603 * The {@code finalize} method is never invoked more than once by a Java
604 * virtual machine for any given object.
605 * <p>
606 * Any exception thrown by the {@code finalize} method causes
607 * the finalization of this object to be halted, but is otherwise
608 * ignored.
609 *
610 * <div class="preview-block">
611 * <div class="preview-comment">
612 * If this object is a {@linkplain java.util.Objects#hasIdentity value object},
613 * this method will never be invoked by the garbage collector.
614 * </div>
615 * </div>
616 *
617 * @apiNote
618 * Classes that embed non-heap resources have many options
619 * for cleanup of those resources. The class must ensure that the
620 * lifetime of each instance is longer than that of any resource it embeds.
621 * {@link java.lang.ref.Reference#reachabilityFence} can be used to ensure that
622 * objects remain reachable while resources embedded in the object are in use.
623 * <p>
624 * A subclass should avoid overriding the {@code finalize} method
625 * unless the subclass embeds non-heap resources that must be cleaned up
626 * before the instance is collected.
627 * Finalizer invocations are not automatically chained, unlike constructors.
628 * If a subclass overrides {@code finalize} it must invoke the superclass
629 * finalizer explicitly.
630 * To guard against exceptions prematurely terminating the finalize chain,
631 * the subclass should use a {@code try-finally} block to ensure
632 * {@code super.finalize()} is always invoked. For example,
633 * {@snippet lang="java":
634 * @Override
635 * protected void finalize() throws Throwable {
636 * try {
|