path: root/guava/src/com/google/common/util/concurrent/ServiceManager.java

/*
 * Copyright (C) 2012 The Guava 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 com.google.common.util.concurrent;

import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.base.Preconditions.checkState;
import static java.util.concurrent.TimeUnit.MILLISECONDS;

import com.google.common.annotations.Beta;
import com.google.common.base.Function;
import com.google.common.base.Objects;
import com.google.common.base.Stopwatch;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableMultimap;
import com.google.common.collect.Lists;
import com.google.common.collect.Maps;
import com.google.common.collect.Ordering;
import com.google.common.collect.Queues;
import com.google.common.util.concurrent.Service.State;

import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Queue;
import java.util.Set;
import java.util.concurrent.Executor;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.logging.Level;
import java.util.logging.Logger;

import javax.annotation.concurrent.GuardedBy;
import javax.annotation.concurrent.Immutable;
import javax.inject.Inject;
import javax.inject.Singleton;

/**
 * A manager for monitoring and controlling a set of {@link Service services}. This class provides
 * methods for {@linkplain #startAsync() starting}, {@linkplain #stopAsync() stopping} and
 * {@linkplain #servicesByState inspecting} a collection of {@linkplain Service services}.
 * Additionally, users can monitor state transitions with the {@link Listener listener} mechanism.
 *
 * <p>While it is recommended that service lifecycles be managed via this class, state transitions
 * initiated via other mechanisms do not impact the correctness of its methods. For example, if the
 * services are started by some mechanism besides {@link #startAsync}, the listeners will be invoked
 * when appropriate and {@link #awaitHealthy} will still work as expected.
 *
 * <p>Here is a simple example of how to use a {@link ServiceManager} to start a server.
 * <pre>   {@code
 * class Server {
 *   public static void main(String[] args) {
 *     Set<Service> services = ...;
 *     ServiceManager manager = new ServiceManager(services);
 *     manager.addListener(new Listener() {
 *         public void stopped() {}
 *         public void healthy() {
 *           // Services have been initialized and are healthy, start accepting requests...
 *         }
 *         public void failure(Service service) {
 *           // Something failed, at this point we could log it, notify a load balancer, or take
 *           // some other action.  For now we will just exit.
 *           System.exit(1);
 *         }
 *       },
 *       MoreExecutors.sameThreadExecutor());
 *
 *     Runtime.getRuntime().addShutdownHook(new Thread() {
 *       public void run() {
 *         // Give the services 5 seconds to stop to ensure that we are responsive to shutdown 
 *         // requests.
 *         try {
 *           manager.stopAsync().awaitStopped(5, TimeUnit.SECONDS);
 *         } catch (TimeoutException timeout) {
 *           // stopping timed out
 *         }
 *       }
 *     });
 *     manager.startAsync();  // start all the services asynchronously
 *   }
 * }}</pre>
 *
 * This class uses the ServiceManager's methods to start all of its services, to respond to service
 * failure and to ensure that when the JVM is shutting down all the services are stopped.
 *
 * @author Luke Sandberg
 * @since 14.0
 */
@Beta
@Singleton
public final class ServiceManager {
  private static final Logger logger = Logger.getLogger(ServiceManager.class.getName());
  
  /**
   * A listener for the aggregate state changes of the services that are under management. Users
   * that need to listen to more fine-grained events (such as when each particular
   * {@link Service service} starts, or terminates), should attach {@link Service.Listener service
   * listeners} to each individual service.
   * 
   * @author Luke Sandberg
   * @since 14.0
   */
  @Beta  // Should come out of Beta when ServiceManager does
  public static interface Listener {
    /** 
     * Called when the service initially becomes healthy.
     * 
     * <p>This will be called at most once after all the services have entered the 
     * {@linkplain State#RUNNING running} state. If any services fail during start up or 
     * {@linkplain State#FAILED fail}/{@linkplain State#TERMINATED terminate} before all other 
     * services have started {@linkplain State#RUNNING running} then this method will not be called.
     */
    void healthy();
    
    /** 
     * Called when the all of the component services have reached a terminal state, either 
     * {@linkplain State#TERMINATED terminated} or {@linkplain State#FAILED failed}.
     */
    void stopped();
    
    /** 
     * Called when a component service has {@linkplain State#FAILED failed}.
     * 
     * @param service The service that failed.
     */
    void failure(Service service);
  }
  
  /**
   * An encapsulation of all of the state that is accessed by the {@linkplain ServiceListener 
   * service listeners}.  This is extracted into its own object so that {@link ServiceListener} 
   * could be made {@code static} and its instances can be safely constructed and added in the 
   * {@link ServiceManager} constructor without having to close over the partially constructed 
   * {@link ServiceManager} instance (i.e. avoid leaking a pointer to {@code this}).
   */
  private final ServiceManagerState state;
  private final ImmutableMap<Service, ServiceListener> services;
  
  /**
   * Constructs a new instance for managing the given services.
   * 
   * @param services The services to manage
   * 
   * @throws IllegalArgumentException if not all services are {@link State#NEW new} or if there are
   *     any duplicate services.
   */
  public ServiceManager(Iterable<? extends Service> services) {
    ImmutableList<Service> copy = ImmutableList.copyOf(services);
    this.state = new ServiceManagerState(copy.size());
    ImmutableMap.Builder<Service, ServiceListener> builder = ImmutableMap.builder();
    Executor executor = MoreExecutors.sameThreadExecutor();
    for (Service service : copy) {
      ServiceListener listener = new ServiceListener(service, state);
      service.addListener(listener, executor);
      // We check the state after adding the listener as a way to ensure that our listener was added
      // to a NEW service.
      checkArgument(service.state() == State.NEW, "Can only manage NEW services, %s", service);
      builder.put(service, listener);
    }
    this.services = builder.build();
  }
  
  /**
   * Constructs a new instance for managing the given services. This constructor is provided so that
   * dependency injection frameworks can inject instances of {@link ServiceManager}.
   * 
   * @param services The services to manage
   * 
   * @throws IllegalStateException if not all services are {@link State#NEW new}.
   */
  @Inject ServiceManager(Set<Service> services) {
    this((Iterable<Service>) services);
  }
  
  /**
   * Registers a {@link Listener} to be {@linkplain Executor#execute executed} on the given 
   * executor. The listener will not have previous state changes replayed, so it is 
   * suggested that listeners are added before any of the managed services are 
   * {@linkplain Service#start started}.
   *
   * <p>There is no guaranteed ordering of execution of listeners, but any listener added through 
   * this method is guaranteed to be called whenever there is a state change.
   *
   * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown 
   * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception 
   * thrown by {@linkplain MoreExecutors#sameThreadExecutor inline execution}) will be caught and
   * logged.
   * 
   * @param listener the listener to run when the manager changes state
   * @param executor the executor in which the the listeners callback methods will be run. For fast,
   *     lightweight listeners that would be safe to execute in any thread, consider 
   *     {@link MoreExecutors#sameThreadExecutor}.
   */
  public void addListener(Listener listener, Executor executor) {
    state.addListener(listener, executor);
  }

  /**
   * Initiates service {@linkplain Service#start startup} on all the services being managed.  It is
   * only valid to call this method if all of the services are {@linkplain State#NEW new}.
   * 
   * @return this
   * @throws IllegalStateException if any of the Services are not {@link State#NEW new} when the 
   *     method is called, {@link State#TERMINATED terminated} or {@link State#FAILED failed}.
   */
  public ServiceManager startAsync() {
    for (Map.Entry<Service, ServiceListener> entry : services.entrySet()) {
      Service service = entry.getKey();
      State state = service.state();
      checkState(state == State.NEW, "Service %s is %s, cannot start it.", service, 
          state);
    }
    for (ServiceListener service : services.values()) {
      service.start();
    }
    return this;
  }
  
  /**
   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy}.  The manager
   * will become healthy after all the component services have reached the {@linkplain State#RUNNING
   * running} state.  
   * 
   * @throws IllegalStateException if the service manager reaches a state from which it cannot 
   *     become {@linkplain #isHealthy() healthy}.
   */
  public void awaitHealthy() {
    state.awaitHealthy();
    checkState(isHealthy(), "Expected to be healthy after starting");
  }
  
  /**
   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy} for no more 
   * than the given time.  The manager will become healthy after all the component services have 
   * reached the {@linkplain State#RUNNING running} state. 
   *
   * @param timeout the maximum time to wait
   * @param unit the time unit of the timeout argument
   * @throws TimeoutException if not all of the services have finished starting within the deadline
   * @throws IllegalStateException if the service manager reaches a state from which it cannot 
   *     become {@linkplain #isHealthy() healthy}.
   */
  public void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException {
    if (!state.awaitHealthy(timeout, unit)) {
      // It would be nice to tell the caller who we are still waiting on, and this information is 
      // likely to be in servicesByState(), however due to race conditions we can't actually tell 
      // which services are holding up healthiness. The current set of NEW or STARTING services is
      // likely to point out the culprit, but may not.  If we really wanted to solve this we could
      // change state to track exactly which services have started and then we could accurately 
      // report on this. But it is only for logging so we likely don't care.
      throw new TimeoutException("Timeout waiting for the services to become healthy.");
    }
    checkState(isHealthy(), "Expected to be healthy after starting");
  }

  /**
   * Initiates service {@linkplain Service#stop shutdown} if necessary on all the services being 
   * managed. 
   *    
   * @return this
   */
  public ServiceManager stopAsync() {
    for (Service service : services.keySet()) {
      service.stop();
    }
    return this;
  }
 
  /**
   * Waits for the all the services to reach a terminal state. After this method returns all
   * services will either be {@link Service.State#TERMINATED terminated} or 
   * {@link Service.State#FAILED failed}
   */
  public void awaitStopped() {
    state.awaitStopped();
  }
  
  /**
   * Waits for the all the services to reach a terminal state for no more than the given time. After
   * this method returns all services will either be {@link Service.State#TERMINATED terminated} or 
   * {@link Service.State#FAILED failed}
   *
   * @param timeout the maximum time to wait
   * @param unit the time unit of the timeout argument
   * @throws TimeoutException if not all of the services have stopped within the deadline
   */
  public void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException {
    if (!state.awaitStopped(timeout, unit)) {
      throw new TimeoutException("Timeout waiting for the services to stop.");
    }
  }
  
  /**
   * Returns true if all services are currently in the {@linkplain State#RUNNING running} state.  
   * 
   * <p>Users who want more detailed information should use the {@link #servicesByState} method to 
   * get detailed information about which services are not running.
   */
  public boolean isHealthy() {
    for (Service service : services.keySet()) {
      if (!service.isRunning()) {
        return false;
      }
    }
    return true;
  }
  
  /**
   * Provides a snapshot of the current state of all the services under management.
   * 
   * <p>N.B. This snapshot it not guaranteed to be consistent, i.e. the set of states returned may
   * not correspond to any particular point in time view of the services. 
   */
  public ImmutableMultimap<State, Service> servicesByState() {
    ImmutableMultimap.Builder<State, Service> builder = ImmutableMultimap.builder();
    for (Service service : services.keySet()) {
      builder.put(service.state(), service);
    }
    return builder.build();
  }
  
  /**
   * Returns the service load times. This value will only return startup times for services that
   * have finished starting.
   *
   * @return Map of services and their corresponding startup time in millis, the map entries will be
   *     ordered by startup time.
   */
  public ImmutableMap<Service, Long> startupTimes() { 
    Map<Service, Long> loadTimeMap = Maps.newHashMapWithExpectedSize(services.size());
    for (Map.Entry<Service, ServiceListener> entry : services.entrySet()) {
      State state = entry.getKey().state();
      if (state != State.NEW && state != State.STARTING) {
        loadTimeMap.put(entry.getKey(), entry.getValue().startupTimeMillis());
      }
    }
    List<Entry<Service, Long>> servicesByStartTime = Ordering.<Long>natural()
        .onResultOf(new Function<Map.Entry<Service, Long>, Long>() {
          @Override public Long apply(Map.Entry<Service, Long> input) {
            return input.getValue();
          }
        })
        .sortedCopy(loadTimeMap.entrySet());
    ImmutableMap.Builder<Service, Long> builder = ImmutableMap.builder();
    for (Map.Entry<Service, Long> entry : servicesByStartTime) {
      builder.put(entry);
    }
    return builder.build();
  }
  
  @Override public String toString() {
    return Objects.toStringHelper(ServiceManager.class)
        .add("services", services.keySet())
        .toString();
  }
  
  /**
   * An encapsulation of all the mutable state of the {@link ServiceManager} that needs to be 
   * accessed by instances of {@link ServiceListener}.
   */
  private static final class ServiceManagerState {
    final Monitor monitor = new Monitor();
    final int numberOfServices;
    /** The number of services that have not finished starting up. */
    @GuardedBy("monitor")
    int unstartedServices;
    /** The number of services that have not reached a terminal state. */
    @GuardedBy("monitor")
    int unstoppedServices;
    /** 
     * Controls how long to wait for all the service manager to either become healthy or reach a 
     * state where it is guaranteed that it can never become healthy.
     */
    final Monitor.Guard awaitHealthGuard = new Monitor.Guard(monitor) {
      @Override public boolean isSatisfied() {
        // All services have started or some service has terminated/failed.
        return unstartedServices == 0 || unstoppedServices != numberOfServices;
      }
    };
    /**
     * Controls how long to wait for all services to reach a terminal state.
     */
    final Monitor.Guard stoppedGuard = new Monitor.Guard(monitor) {
      @Override public boolean isSatisfied() {
        return unstoppedServices == 0;
      }
    };
    /** The listeners to notify during a state transition. */
    @GuardedBy("monitor")
    final List<ListenerExecutorPair> listeners = Lists.newArrayList();
    /**
     * The queue of listeners that are waiting to be executed.
     *
     * <p>Enqueue operations should be protected by {@link #monitor} while dequeue operations should
     * be protected by the implicit lock on this object. This is to ensure that listeners are
     * executed in the correct order and also so that a listener can not hold the {@link #monitor} 
     * for an arbitrary amount of time (listeners can only block other listeners, not internal state
     * transitions). We use a concurrent queue implementation so that enqueues can be executed 
     * concurrently with dequeues.
     */
    @GuardedBy("queuedListeners")
    final Queue<Runnable> queuedListeners = Queues.newConcurrentLinkedQueue();
    
    ServiceManagerState(int numberOfServices) {
      this.numberOfServices = numberOfServices;
      this.unstoppedServices = numberOfServices;
      this.unstartedServices = numberOfServices;
    }
    
    void addListener(Listener listener, Executor executor) {
      checkNotNull(listener, "listener");
      checkNotNull(executor, "executor");
      monitor.enter();
      try {
        // no point in adding a listener that will never be called
        if (unstartedServices > 0 || unstoppedServices > 0) {
          listeners.add(new ListenerExecutorPair(listener, executor));
        }
      } finally {
        monitor.leave();
      }
    }
    
    void awaitHealthy() {
      monitor.enter();
      try {
        monitor.waitForUninterruptibly(awaitHealthGuard);
      } finally {
        monitor.leave();
      }
    }
    
    boolean awaitHealthy(long timeout, TimeUnit unit) {
      monitor.enter();
      try {
        if (monitor.waitForUninterruptibly(awaitHealthGuard, timeout, unit)) {
          return true;
        }
        return false;
      } finally {
        monitor.leave();
      }
    }
    
    void awaitStopped() {
      monitor.enter();
      try {
        monitor.waitForUninterruptibly(stoppedGuard);
      } finally {
        monitor.leave();
      }
    }
    
    boolean awaitStopped(long timeout, TimeUnit unit) {
      monitor.enter();
      try {
        return monitor.waitForUninterruptibly(stoppedGuard, timeout, unit);
      } finally {
        monitor.leave();
      }
    }
    
    /**
     * This should be called when a service finishes starting up.
     * 
     * @param currentlyHealthy whether or not the service that finished starting was healthy at the 
     *        time that it finished starting. 
     */
    @GuardedBy("monitor")
    private void serviceFinishedStarting(Service service, boolean currentlyHealthy) {
      checkState(unstartedServices > 0, 
          "All services should have already finished starting but %s just finished.", service);
      unstartedServices--;
      if (currentlyHealthy && unstartedServices == 0 && unstoppedServices == numberOfServices) {
        // This means that the manager is currently healthy, or at least it should have been
        // healthy at some point from some perspective. Calling isHealthy is not currently
        // guaranteed to return true because any service could fail right now. However, the
        // happens-before relationship enforced by the monitor ensures that this method was called
        // before either serviceTerminated or serviceFailed, so we know that the manager was at 
        // least healthy for some period of time. Furthermore we are guaranteed that this call to
        // healthy() will be before any call to terminated() or failure(Service) on the listener.
        // So it is correct to execute the listener's health() callback.
        for (final ListenerExecutorPair pair : listeners) {
          queuedListeners.add(new Runnable() {
            @Override public void run() {
              pair.execute(new Runnable() {
                @Override public void run() {
                  pair.listener.healthy();
                }
              });
            }
          });
        }
      }
    }
    
    /**
     * This should be called when a service is {@linkplain State#TERMINATED terminated}.
     */
    @GuardedBy("monitor")
    private void serviceTerminated(Service service) {
      serviceStopped(service);
    }
    
    /**
     * This should be called when a service is {@linkplain State#FAILED failed}.
     */
    @GuardedBy("monitor")
    private void serviceFailed(final Service service) {
      for (final ListenerExecutorPair pair : listeners) {
        queuedListeners.add(new Runnable() {
          @Override public void run() {
            pair.execute(new Runnable() {
              @Override public void run() {
                pair.listener.failure(service);
              }
            });
          }
        });
      }
      serviceStopped(service);
    }
    
    /**
     * Should be called whenever a service reaches a terminal state (
     * {@linkplain State#TERMINATED terminated} or 
     * {@linkplain State#FAILED failed}).
     */
    @GuardedBy("monitor")
    private void serviceStopped(Service service) {
      checkState(unstoppedServices > 0, 
          "All services should have already stopped but %s just stopped.", service);
      unstoppedServices--;
      if (unstoppedServices == 0) {
        checkState(unstartedServices == 0, 
            "All services are stopped but %d services haven't finished starting", 
            unstartedServices);
        for (final ListenerExecutorPair pair : listeners) {
          queuedListeners.add(new Runnable() {
            @Override public void run() {
              pair.execute(new Runnable() {
                @Override public void run() {
                  pair.listener.stopped();
                }
              });
            }
          });
        }
        // no more listeners could possibly be called, so clear them out
        listeners.clear();
      }
    }
    
    /** 
     * Attempts to execute all the listeners in {@link #queuedListeners}.
     */
    private void executeListeners() {
      checkState(!monitor.isOccupiedByCurrentThread(), 
          "It is incorrect to execute listeners with the monitor held.");
      synchronized (queuedListeners) {
        Runnable listener;
        while ((listener = queuedListeners.poll()) != null) {
          listener.run();
        }
      }
    }
  }

  /**
   * A {@link Service} that wraps another service and times how long it takes for it to start and 
   * also calls the {@link ServiceManagerState#serviceFinishedStarting}, 
   * {@link ServiceManagerState#serviceTerminated} and {@link ServiceManagerState#serviceFailed}
   * according to its current state.
   */
  private static final class ServiceListener implements Service.Listener {
    @GuardedBy("watch")  // AFAICT Stopwatch is not thread safe so we need to protect accesses
    final Stopwatch watch = new Stopwatch();
    final Service service;
    final ServiceManagerState state;
    
    /**
     * @param service the service that 
     */
    ServiceListener(Service service, ServiceManagerState state) {
      this.service = service;
      this.state = state;
    }
    
    @Override public void starting() {
      // This can happen if someone besides the ServiceManager starts the service, in this case
      // our timings may be inaccurate.
      startTimer();
    }
    
    @Override public void running() {
      state.monitor.enter();
      try {
        finishedStarting(true);
      } finally {
        state.monitor.leave();
        state.executeListeners();
      }
    }
    
    @Override public void stopping(State from) {
      if (from == State.STARTING) {
        state.monitor.enter();
        try {
          finishedStarting(false);
        } finally {
          state.monitor.leave();
          state.executeListeners();
        }
      }
    }
    
    @Override public void terminated(State from) {
      logger.info("Service " + service + " has terminated. Previous state was " + from + " state.");
      state.monitor.enter();
      try {
        if (from == State.NEW) {
          // startTimer is idempotent, so this is safe to call and it may be necessary if no one has
          // started the timer yet.
          startTimer(); 
          finishedStarting(false);
        }
        state.serviceTerminated(service);
      } finally {
        state.monitor.leave();
        state.executeListeners();
      }
    }
    
    @Override public void failed(State from, Throwable failure) {
      logger.log(Level.SEVERE, "Service " + service + " has failed in the " + from + " state.", 
          failure);
      state.monitor.enter();
      try {
        if (from == State.STARTING) {
          finishedStarting(false);
        }
        state.serviceFailed(service);
      } finally {
        state.monitor.leave();
        state.executeListeners();
      }
    }
    
    /** 
     * Stop the stopwatch, log the startup time and decrement the startup latch
     *  
     * @param currentlyHealthy whether or not the service that finished starting is currently 
     *        healthy 
     */
    @GuardedBy("monitor")
    void finishedStarting(boolean currentlyHealthy) {
      synchronized (watch) {
        watch.stop();
        logger.log(Level.INFO, "Started " + service + " in " + startupTimeMillis() + " ms.");
      }
      state.serviceFinishedStarting(service, currentlyHealthy);
    }
    
    void start() {
      startTimer();
      service.start();
    }
  
    /** Start the timer if it hasn't been started. */
    void startTimer() {
      synchronized (watch) {
        if (!watch.isRunning()) { // only start the watch once.
          watch.start();
          logger.log(Level.INFO, "Starting {0}", service);
        }
      }
    }
    
    /** Returns the amount of time it took for the service to finish starting in milliseconds. */
    synchronized long startupTimeMillis() {
      synchronized (watch) {
        return watch.elapsed(MILLISECONDS);
      }
    }
  }
  
  /** Simple value object binding a listener to its executor. */
  @Immutable private static final class ListenerExecutorPair {
    final Listener listener;
    final Executor executor;
    
    ListenerExecutorPair(Listener listener, Executor executor) {
      this.listener = listener;
      this.executor = executor;
    }
    
    /**
     * Executes the given {@link Runnable} on {@link #executor} logging and swallowing all 
     * exceptions
     */
    void execute(Runnable runnable) {
      try {
        executor.execute(runnable);
      } catch (Exception e) {
        logger.log(Level.SEVERE, "Exception while executing listener " + listener 
            + " with executor " + executor, e);
      }
    }
  }
}