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 interrupt status needs to be cleared
387 vthread.getAndClearInterrupt();
388 throw e;
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++;
|
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 * an {@linkplain Class#isIdentity identity class} or a {@linkplain Class#isValue value class}.
40 * See {@jls The Java Language Specification 8.1.1.5 Value Classes}.
41 * Use of value class instances for synchronization, mutexes, or with
42 * {@linkplain java.lang.ref.Reference object references} result 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 Class#isValue() value object},
314 * it does 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 Class#isValue() 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 Class#isValue() value object},
347 * it does 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 Class#isValue() 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 Class#isValue() value object},
371 * it does 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 Class#isValue() 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 Class#isValue() value object},
402 * it does 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 Class#isValue() 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 interrupt status needs to be cleared
429 vthread.getAndClearInterrupt();
430 throw e;
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 * @apiNote
504 * The recommended approach to waiting is to check the condition being awaited in
505 * a {@code while} loop around the call to {@code wait}, as shown in the example
506 * below. Among other things, this approach avoids problems that can be caused
507 * by spurious wakeups.
508 *
509 * {@snippet lang=java :
510 * synchronized (obj) {
511 * while ( <condition does not hold and timeout not exceeded> ) {
512 * long timeoutMillis = ... ; // recompute timeout values
513 * int nanos = ... ;
514 * obj.wait(timeoutMillis, nanos);
515 * }
516 * ... // Perform action appropriate to condition or timeout
517 * }
518 * }
519 *
520 * <div class="preview-block">
521 * <div class="preview-comment">
522 * If this object is a {@linkplain Class#isValue() value object},
523 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
524 * </div>
525 * </div>
526 * @param timeoutMillis the maximum time to wait, in milliseconds
527 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
528 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
529 * or if the value of {@code nanos} is out of range
530 * @throws IllegalMonitorStateException if the current thread is not
531 * the owner of the object's monitor or
532 * if this object is a {@linkplain Class#isValue() value object}.
533 * @throws InterruptedException if any thread interrupted the current thread before or
534 * while the current thread was waiting. The <em>interrupted status</em> of the
535 * current thread is cleared when this exception is thrown.
536 * @see #notify()
537 * @see #notifyAll()
538 * @see #wait()
539 * @see #wait(long)
540 */
541 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
542 if (timeoutMillis < 0) {
543 throw new IllegalArgumentException("timeoutMillis value is negative");
544 }
545
546 if (nanos < 0 || nanos > 999999) {
547 throw new IllegalArgumentException(
548 "nanosecond timeout value out of range");
549 }
550
551 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
552 timeoutMillis++;
|