Class SingletonScope

core/src/com/google/inject/internal/SingletonScope.java:63–310

One instance per Injector. Also see @Singleton. Introduction from the author: Implementation of this class seems unreasonably complicated at the first sight. I fully agree with you, that the beast below is very complex and it's hard to reason on how does it work or not. S

 * @author timofeyb (Timothy Basanov)
 */
public class SingletonScope implements Scope {

  /** A sentinel value representing null. */
  private static final Object NULL = new Object();

  /**
   * Allows us to detect when circular proxies are necessary. It's only used during singleton
   * instance initialization, after initialization direct access through volatile field is used.
   *
   * <p>NB: Factory uses {@link Key}s as a user locks ids, different injectors can share them.
   * Cycles are detected properly as cycle detection does not rely on user locks ids, but error
   * message generated could be less than ideal.
   */
  // TODO(user): we may use one factory per injector tree for optimization reasons
  private static final CycleDetectingLockFactory<Key<?>> cycleDetectingLockFactory =
      new CycleDetectingLockFactory<Key<?>>();

  /**
   * Provides singleton scope with the following properties:
   *
   * <ul>
   *   <li>creates no more than one instance per Key as a creator is used no more than once
   *   <li>result is cached and returned quickly on subsequent calls
   *   <li>exception in a creator is not treated as instance creation and is not cached
   *   <li>creates singletons in parallel whenever possible
   *   <li>waits for dependent singletons to be created even across threads and when dependencies
   *       are shared as long as no circular dependencies are detected
   *   <li>returns circular proxy only when circular dependencies are detected
   *   <li>aside from that, blocking synchronization is only used for proxy creation and
   *       initialization
   * </ul>
   *
   * @see CycleDetectingLockFactory
   */
  @Override
  public <T> Provider<T> scope(final Key<T> key, final Provider<T> creator) {
    /** Locking strategy: */
    return new Provider<T>() {
      /**
       * The lazily initialized singleton instance. Once set, this will either have type T or will
       * be equal to NULL. Would never be reset to null.
       *
       * <p>Locking strategy: double-checked locking for quick exit when scope is initialized.
       */
      volatile Object instance;

      /**
       * Circular proxies are used when potential deadlocks are detected. Guarded by itself.
       * ConstructionContext is not thread-safe, so each call should be synchronized.
       *
       * <p>Locking strategy: manipulations with proxies list or instance initialization.
       */
      final ConstructionContext<T> constructionContext = new ConstructionContext<>();

      /**
       * For each binding there is a separate lock that we hold during object creation.
       *
       * <p>Locking strategy: singleton instance creation.