1 /*
2 * Copyright 2020-2022 The OSHI Project Contributors
3 * SPDX-License-Identifier: MIT
4 */
5 package oshi.annotation.concurrent;
6
7 import java.lang.annotation.Documented;
8
9 /**
10 * The presence of this annotation indicates that the author believes the class to be immutable and hence inherently
11 * thread-safe. An immutable class is one where the state of an instance cannot be <i>seen</i> to change. As a result
12 * <ul>
13 * <li>All public fields must be {@code final}</li>
14 * <li>All public final reference fields are either {@code null} or refer to other immutable objects</li>
15 * <li>Constructors and methods do not publish references to any potentially mutable internal state.</li>
16 * </ul>
17 * Performance optimization may mean that instances of an immutable class may have mutable internal state. The critical
18 * point is that callers cannot tell the difference. For example {@link String} is an immutable class, despite having an
19 * internal int that is non-final but used as a cache for {@link String#hashCode()}.
20 * <p>
21 * Immutable objects are inherently thread-safe; they may be passed between threads or published without
22 * synchronization.
23 * <p>
24 * This annotation is intended for internal use in OSHI as a temporary workaround until it is available in
25 * {@code jakarta.annotations}.
26 */
27 @Documented
28 public @interface Immutable {
29 }