Page History

During initialization of a shared object, the object must only be accessible to the thread constructing it. However, the object can be published safely published (that is, made visible to other threads) once it is initialized. The Java Memory Model (JMM) allows multiple threads to observe the object after its initialization has begun, but before it has concluded. Consequently, it is important to ensure that a partially initialized object is not published.

This guideline prohibits publishing a reference to a partially initialized member object instance before initialization completes while has concluded. Guideline TSM01-J. Do not let the (this) reference escape during object construction prohibits the this reference of the current object from escaping.

...

This noncompliant code example constructs a Helper object in the initialize() method of the Foo class Foo. The helper field is object's fields are initialized by Helper's its constructor.

class Foo {
  private Helper helper;

  public Helper getHelper() {
    return helper;
  }

  public void initialize() {
    helper = new Helper(42);
  }
}

public class Helper {
  private int n;

  public Helper(int n) {
    this.n = n;
  }
  // ...
}

If a thread accesses helper using the getHelper() method before the initialize() method has been called, the thread will observe an uninitialized helper field. Later, if one thread calls initialize(), and another calls getHelper(), the second thread might observe one of the following:
*the helper reference as null, or it might observe
*a fully-initialized Helper object with the n field set to 42, or it might observe
*a partially-initialized Helper object with an uninitialized n which contains the default value 0.

In particular, the JMM permits compilers to allocate memory for the new Helper object and assign it to the helper field before initializing it. In other words, the compiler can reorder the write to the helper instance field with the write that initializes the Helper object (that is, this.n = n) such that the former occurs first. This exposes a race window during which other threads may observe a partially-initialized Helper object instance.

There is a separate issue in that, : if two threads call initialize(), then two Helper objects are created. This is a performance issue and not a correctness issue because n will be properly initialized and the unused Helper objects will be garbage-collected.

Compliant Solution (Synchronization)

Publishing The publication of partially - constructed object reference references can be prevented by using method synchronization, as shown by in this compliant solution.

class Foo {
  private Helper helper;

  public synchronized Helper getHelper() {
    return helper;
  }

  public synchronized void initialize() {
    helper = new Helper(42);
  }
}

...

If the helper field is declared as final, it is guaranteed to be fully constructed before its reference is made visible.

...

However, this solution requires that thethe assignment of a new {{helperHelper}} fieldinstance is assigned to a new object during construction{{helpger}} from Foo's constructor. According to the _Java Language Specification_, Section 17.5.2, "Reading Final Fields During Construction" \[[JLS 052005|AA. Java References#JLS 05]\]:

A read of a final field of an object within the thread that constructs that object is ordered with respect to the initialization of that field within the constructor by the usual happens-before rules. If the read occurs after the field is set in the constructor, it sees the value the final field is assigned, otherwise it sees the default value.

Consequently, the reference to the helper field instance should not be published before the Foo class Foo's constructor has finished its initialization (see guideline TSM01-J. Do not let the (this) reference escape during object construction).

...

The helper field is declared as final to guarantee that the vector is created before any accesses take place. It can be initialized safely initialized by invoking the synchronized initialize() method, which is synchronized and checks ensures that only one Helper object is os ever added to the vector. If getHelper() is invoked before initialize(), it calls initialize() to avoid the possibility of a null-pointer dereference de-reference by the client. The getHelper() method does not require synchronization to simply return Helper, and because and—because the synchronized initialize() method also checks to make sure helper is empty before adding a new Helper object, there object—there is no possibility of exploiting a race condition to add a second object to the vector.

...

In this compliant solution, the helper field is initialized in a static block. When initialized statically, an object is guaranteed to be fully initialized statically initialized, ensuring that the object referenced by the field is fully initilalized before its reference is made visible.

// Immutable Foo
final class Foo {
  private static final Helper helper = new Helper(42);

  public static Helper getHelper() {
    return helper;
  }
}

This requires the helper field to be declared static. Although not a requirement, it is recommended that the helper field should be declared final to document the class's immutability.

According to JSR-133, Section 9.2.3, "Static Final Fields"  \[[JSR-133 042004|AA. Java References#JSR-133 04]\]:

...

Compliant Solution (Immutable object - Final fields, Volatile Reference)

The Java memoryJMM model guarantees that any final fields of an object are fully initialized before a published object becomes visible \[[Goetz 062006|AA. Java References#Goetz 06]\]. By declaring {{n}} as final, the {{Helper}} class is made [immutable|BB. Definitions#immutable]. Furthermore, if the {{helper}} field is declared {{volatile}} in compliance with guideline [VNA01-J. Ensure visibility of shared references to immutable objects|VNA01-J. Ensure visibility of shared references to immutable objects], {{Helper}}'s reference is guaranteed to be made visible to any thread that calls {{getHelper()}} after {{Helper}} has been fully initialized.

...

This compliant solution requires that helper be declared as volatile and class Helper be immutable. If it were not immutable, the code would violate guideline VNA06-J. Do not assume that declaring an object reference volatile guarantees visibility of its members, and additional synchronization would be necessary (see the next compliant solution). And if the helper field were not non-volatile, it would violate guideline VNA01-J. Ensure visibility of shared references to immutable objects.

Similarly, a public static factory method that returns a new instance of Helper can be provided in the Helper class Helper. This approach allows the Helper instance to be created in a private constructor.

Compliant Solution (Mutable Thread-safe Object, Volatile Reference)

If Helper is mutable , but thread-safe, it can be published safely published by declaring the helper field in the Foo class Foo as volatile.

class Foo {
  private volatile Helper helper;

  public Helper getHelper() {
    return helper;
  }

  public void initialize() {
    helper = new Helper(42);
  }
}

// Mutable but thread-safe Helper
public class Helper {
  private volatile int n;
  private final Object lock = new Object();

  public Helper(int n) {
    this.n = n;
  }

  public void setN(int value) {
    synchronized (lock) {
      n = value;
    }
  }
}

Because the Helper object can change state after its construction, synchronization is necessary to ensure the visibility of mutable members after initial publication. Consequently, the setN() method is synchronized to provide the visibility of the n field in this compliant solution (see guideline VNA06-J. Do not assume that declaring an object reference volatile guarantees visibility of its members).

If the Helper class is not synchronized properly synchronized, declaring helper as volatile in the Foo class Foo only guarantees the visibility of the initial publication of Helper and not of subsequent state changes. Consequently, volatile references alone are inadequate for publishing objects that are not thread-safe.

If the helper field in the Foo class Foo is not declared as volatile, the n field n should be declared as volatile so that a happens-before relationship is established between the initialization of n and the write of Helper to the helper field helper. This is in compliance with guideline VNA06-J. Do not assume that declaring an object reference volatile guarantees visibility of its members. This is required only required when the caller (class Foo) cannot be trusted to declare helper as volatile.

Because the the Helper class is declared as public, it uses a private lock to handle synchronization in conformance with guideline LCK00-J. Use private final lock objects to synchronize classes that may interact with untrusted code.

Exceptions

CON28TSM03-EX1: Classes that prevent partially initialized objects from being used may publish partially initialized objects. This may be implemented, for example, by setting a volatile boolean flag in the last statement of the initializing code and then ensuring this flag was set before allowing the execution of any class methods to execute.

The following compliant solution illustrates this technique:

public class Helper {
  private int n;
  private volatile boolean initialized; // Defaults to false

  public Helper(int n) {
    this.n = n;
    this.initialized = true;
  }

  public void doSomething() {
    if (!initialized) {
      throw new SecurityException("Cannot use partially initialized instance");
    }
    // ...
  }
  // ...
}

This technique ensures that even if the reference to the Helper object instance is published before its initialization is over, the instance is unusable. The instance is unusable because every method within Helper must check the flag to determine whether the initialization has finished.

...

Failing to synchronize access to shared mutable data can cause different threads to observe different states of the object or a partially initialized object.

...

References

\[[API 062006|AA. Java References#API 06]\]
\[[Bloch 012001|AA. Java References#Bloch 01]\] Item 48: "Synchronize access to shared mutable data"
\[[Goetz 062006|AA. Java References#Goetz 06]\] Section 3.5.3 "Safe Publication Idioms"
\[[Goetz 072007|AA. Java References#Goetz 07]\] Pattern #2: "one-time safe publication"
\[[JPL 062006|AA. Java References#JPL 06]\] 14.10.2. "Final Fields and Security"
\[[Pugh 042004|AA. Java References#Pugh 04]\]

...