/*
 * Copyright (C) 2014 The Dagger Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package dagger.producers;

import com.google.common.util.concurrent.ListenableFuture;
import com.google.errorprone.annotations.CheckReturnValue;
import dagger.internal.Beta;

/**
 * An interface that represents the production of a type {@code T}. You can also inject
 * {@code Producer<T>} instead of {@code T}, which will delay the execution of any code that
 * produces the {@code T} until {@link #get} is called.
 *
 * <p>For example, you might inject {@code Producer} to lazily choose between several different
 * implementations of some type: <pre><code>
 *   {@literal @Produces ListenableFuture<Heater>} getHeater(
 *       HeaterFlag flag,
 *       {@literal @Electric Producer<Heater>} electricHeater,
 *       {@literal @Gas Producer<Heater>} gasHeater) {
 *     return flag.useElectricHeater() ? electricHeater.get() : gasHeater.get();
 *   }
 * </code></pre>
 *
 * <p>Here is a complete example that demonstrates how calling {@code get()} will cause each
 * method to be executed: <pre><code>
 *
 *   {@literal @}ProducerModule
 *   final class MyModule {
 *     {@literal @Produces ListenableFuture<A>} a() {
 *       System.out.println("a");
 *       return Futures.immediateFuture(new A());
 *     }
 *
 *     {@literal @Produces ListenableFuture<B>} b(A a) {
 *       System.out.println("b");
 *       return Futures.immediateFuture(new B(a));
 *     }
 *
 *     {@literal @Produces ListenableFuture<C>} c(B b) {
 *       System.out.println("c");
 *       return Futures.immediateFuture(new C(b));
 *     }
 *
 *     {@literal @Produces @Delayed ListenableFuture<C>} delayedC(A a, {@literal Producer<C>} c) {
 *       System.out.println("delayed c");
 *       return c.get();
 *     }
 *   }
 *
 *   {@literal @}ProductionComponent(modules = MyModule.class)
 *   interface MyComponent {
 *     {@literal @Delayed ListenableFuture<C>} delayedC();
 *   }
 * </code></pre>
 * Suppose we instantiate the generated implementation of this component and call
 * {@code delayedC()}: <pre><code>
 *   MyComponent component = DaggerMyComponent
 *       .builder()
 *       .executor(MoreExecutors.directExecutor())
 *       .build();
 *   System.out.println("Constructed component");
 *   {@literal ListenableFuture<C>} cFuture = component.delayedC();
 *   System.out.println("Retrieved future");
 *   C c = cFuture.get();
 *   System.out.println("Retrieved c");
 * </code></pre>
 * Here, we're using {@code MoreExecutors.directExecutor} in order to illustrate how each call
 * directly causes code to execute. The above code will print: <pre><code>
 *   Constructed component
 *   a
 *   delayed c
 *   b
 *   c
 *   Retrieved future
 *   Retrieved c
 * </code></pre>
 *
 * @since 2.0
 */
@Beta
public interface Producer<T> {
  /**
   * Returns a future representing a running task that produces a value. Calling this method will
   * trigger the submission of this task to the executor, if it has not already been triggered. In
   * order to trigger this task's submission, the transitive dependencies required to produce the
   * {@code T} will be submitted to the executor, as their dependencies become available.
   *
   * <p>If the key is bound to a {@link Produces} method, then calling this method multiple times
   * will return the same future.
   */
  @CheckReturnValue
  ListenableFuture<T> get();
}