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
54 * example, no cast is required in this code fragment:</p>
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++;
|
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 * <div class="preview-block">
36 * <div class="preview-comment">
37 * When preview features are enabled, subclasses of {@code java.lang.Object} can be either
38 * an {@linkplain Class#isIdentity identity class} or a {@linkplain Class#isValue value class}.
39 * See {@jls The Java Language Specification 8.1.1.5 Value Classes}.
40 * Use of value class instances for synchronization, mutexes, or with
41 * {@linkplain java.lang.ref.Reference object references} result in
42 * {@link IdentityException}.
43 * </div>
44 * </div>
45 *
46 * @see java.lang.Class
47 * @since 1.0
48 */
49 public class Object {
50
51 /**
52 * Constructs a new object.
53 */
54 @IntrinsicCandidate
55 public Object() {}
56
57 /**
58 * Returns the runtime class of this {@code Object}. The returned
59 * {@code Class} object is the object that is locked by {@code
60 * static synchronized} methods of the represented class.
61 *
62 * <p><b>The actual result type is {@code Class<? extends |X|>}
63 * where {@code |X|} is the erasure of the static type of the
64 * expression on which {@code getClass} is called.</b> For
65 * example, no cast is required in this code fragment:</p>
289 * <p>
290 * The awakened thread will not be able to proceed until the current
291 * thread relinquishes the lock on this object. The awakened thread will
292 * compete in the usual manner with any other threads that might be
293 * actively competing to synchronize on this object; for example, the
294 * awakened thread enjoys no reliable privilege or disadvantage in being
295 * the next thread to lock this object.
296 * <p>
297 * This method should only be called by a thread that is the owner
298 * of this object's monitor. A thread becomes the owner of the
299 * object's monitor in one of three ways:
300 * <ul>
301 * <li>By executing a synchronized instance method of that object.
302 * <li>By executing the body of a {@code synchronized} statement
303 * that synchronizes on the object.
304 * <li>For objects of type {@code Class,} by executing a
305 * static synchronized method of that class.
306 * </ul>
307 * <p>
308 * Only one thread at a time can own an object's monitor.
309 * <div class="preview-block">
310 * <div class="preview-comment">
311 * If this object is a {@linkplain Class#isValue() value object},
312 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
313 * </div>
314 * </div>
315 *
316 * @throws IllegalMonitorStateException if the current thread is not
317 * the owner of this object's monitor or
318 * if this object is a {@linkplain Class#isValue() value object}.
319 * @see java.lang.Object#notifyAll()
320 * @see java.lang.Object#wait()
321 */
322 @IntrinsicCandidate
323 public final native void notify();
324
325 /**
326 * Wakes up all threads that are waiting on this object's monitor. A
327 * thread waits on an object's monitor by calling one of the
328 * {@code wait} methods.
329 * <p>
330 * The awakened threads will not be able to proceed until the current
331 * thread relinquishes the lock on this object. The awakened threads
332 * will compete in the usual manner with any other threads that might
333 * be actively competing to synchronize on this object; for example,
334 * the awakened threads enjoy no reliable privilege or disadvantage in
335 * being the next thread to lock this object.
336 * <p>
337 * This method should only be called by a thread that is the owner
338 * of this object's monitor. See the {@code notify} method for a
339 * description of the ways in which a thread can become the owner of
340 * a monitor.
341 *
342 * <div class="preview-block">
343 * <div class="preview-comment">
344 * If this object is a {@linkplain Class#isValue() value object},
345 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
346 * </div>
347 * </div>
348 *
349 * @throws IllegalMonitorStateException if the current thread is not
350 * the owner of this object's monitor or
351 * if this object is a {@linkplain Class#isValue() value object}.
352 * @see java.lang.Object#notify()
353 * @see java.lang.Object#wait()
354 */
355 @IntrinsicCandidate
356 public final native void notifyAll();
357
358 /**
359 * Causes the current thread to wait until it is awakened, typically
360 * by being <em>notified</em> or <em>interrupted</em>.
361 * <p>
362 * In all respects, this method behaves as if {@code wait(0L, 0)}
363 * had been called. See the specification of the {@link #wait(long, int)} method
364 * for details.
365 *
366 * <div class="preview-block">
367 * <div class="preview-comment">
368 * If this object is a {@linkplain Class#isValue() value object},
369 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
370 * </div>
371 * </div>
372 *
373 * @throws IllegalMonitorStateException if the current thread is not
374 * the owner of the object's monitor or
375 * if this object is a {@linkplain Class#isValue() value object}.
376 * @throws InterruptedException if any thread interrupted the current thread before or
377 * while the current thread was waiting. The <em>interrupted status</em> of the
378 * current thread is cleared when this exception is thrown.
379 * @see #notify()
380 * @see #notifyAll()
381 * @see #wait(long)
382 * @see #wait(long, int)
383 */
384 public final void wait() throws InterruptedException {
385 wait(0L);
386 }
387
388 /**
389 * Causes the current thread to wait until it is awakened, typically
390 * by being <em>notified</em> or <em>interrupted</em>, or until a
391 * certain amount of real time has elapsed.
392 * <p>
393 * In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
394 * had been called. See the specification of the {@link #wait(long, int)} method
395 * for details.
396 *
397 * <div class="preview-block">
398 * <div class="preview-comment">
399 * If this object is a {@linkplain Class#isValue() value object},
400 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
401 * </div>
402 * </div>
403 *
404 * @param timeoutMillis the maximum time to wait, in milliseconds
405 * @throws IllegalArgumentException if {@code timeoutMillis} is negative
406 * @throws IllegalMonitorStateException if the current thread is not
407 * the owner of the object's monitor or
408 * if this object is a {@linkplain Class#isValue() value object}.
409 * @throws InterruptedException if any thread interrupted the current thread before or
410 * while the current thread was waiting. The <em>interrupted status</em> of the
411 * current thread is cleared when this exception is thrown.
412 * @see #notify()
413 * @see #notifyAll()
414 * @see #wait()
415 * @see #wait(long, int)
416 */
417 public final void wait(long timeoutMillis) throws InterruptedException {
418 if (timeoutMillis < 0) {
419 throw new IllegalArgumentException("timeout value is negative");
420 }
421
422 if (Thread.currentThread() instanceof VirtualThread vthread) {
423 try {
424 wait0(timeoutMillis);
425 } catch (InterruptedException e) {
426 // virtual thread's interrupt status needs to be cleared
427 vthread.getAndClearInterrupt();
428 throw e;
498 * this exception is thrown. This exception is not thrown until the lock status of
499 * this object has been restored as described above.
500 *
501 * @apiNote
502 * The recommended approach to waiting is to check the condition being awaited in
503 * a {@code while} loop around the call to {@code wait}, as shown in the example
504 * below. Among other things, this approach avoids problems that can be caused
505 * by spurious wakeups.
506 *
507 * {@snippet lang=java :
508 * synchronized (obj) {
509 * while ( <condition does not hold and timeout not exceeded> ) {
510 * long timeoutMillis = ... ; // recompute timeout values
511 * int nanos = ... ;
512 * obj.wait(timeoutMillis, nanos);
513 * }
514 * ... // Perform action appropriate to condition or timeout
515 * }
516 * }
517 *
518 * <div class="preview-block">
519 * <div class="preview-comment">
520 * If this object is a {@linkplain Class#isValue() value object},
521 * it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
522 * </div>
523 * </div>
524 * @param timeoutMillis the maximum time to wait, in milliseconds
525 * @param nanos additional time, in nanoseconds, in the range 0-999999 inclusive
526 * @throws IllegalArgumentException if {@code timeoutMillis} is negative,
527 * or if the value of {@code nanos} is out of range
528 * @throws IllegalMonitorStateException if the current thread is not
529 * the owner of the object's monitor or
530 * if this object is a {@linkplain Class#isValue() value object}.
531 * @throws InterruptedException if any thread interrupted the current thread before or
532 * while the current thread was waiting. The <em>interrupted status</em> of the
533 * current thread is cleared when this exception is thrown.
534 * @see #notify()
535 * @see #notifyAll()
536 * @see #wait()
537 * @see #wait(long)
538 */
539 public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
540 if (timeoutMillis < 0) {
541 throw new IllegalArgumentException("timeoutMillis value is negative");
542 }
543
544 if (nanos < 0 || nanos > 999999) {
545 throw new IllegalArgumentException(
546 "nanosecond timeout value out of range");
547 }
548
549 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
550 timeoutMillis++;
|