001/*
002 * Copyright (C) 2012 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.util.concurrent;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.base.Preconditions.checkState;
020import static com.google.common.base.Predicates.equalTo;
021import static com.google.common.base.Predicates.in;
022import static com.google.common.base.Predicates.instanceOf;
023import static com.google.common.base.Predicates.not;
024import static com.google.common.util.concurrent.MoreExecutors.directExecutor;
025import static com.google.common.util.concurrent.Service.State.FAILED;
026import static com.google.common.util.concurrent.Service.State.NEW;
027import static com.google.common.util.concurrent.Service.State.RUNNING;
028import static com.google.common.util.concurrent.Service.State.STARTING;
029import static com.google.common.util.concurrent.Service.State.STOPPING;
030import static com.google.common.util.concurrent.Service.State.TERMINATED;
031import static java.util.concurrent.TimeUnit.MILLISECONDS;
032
033import com.google.common.annotations.GwtIncompatible;
034import com.google.common.annotations.J2ktIncompatible;
035import com.google.common.base.Function;
036import com.google.common.base.MoreObjects;
037import com.google.common.base.Stopwatch;
038import com.google.common.collect.Collections2;
039import com.google.common.collect.ImmutableCollection;
040import com.google.common.collect.ImmutableList;
041import com.google.common.collect.ImmutableMap;
042import com.google.common.collect.ImmutableSet;
043import com.google.common.collect.ImmutableSetMultimap;
044import com.google.common.collect.Lists;
045import com.google.common.collect.Maps;
046import com.google.common.collect.MultimapBuilder;
047import com.google.common.collect.Multimaps;
048import com.google.common.collect.Multiset;
049import com.google.common.collect.Ordering;
050import com.google.common.collect.SetMultimap;
051import com.google.common.util.concurrent.Service.State;
052import com.google.errorprone.annotations.CanIgnoreReturnValue;
053import com.google.errorprone.annotations.concurrent.GuardedBy;
054import com.google.j2objc.annotations.WeakOuter;
055import java.lang.ref.WeakReference;
056import java.util.Collections;
057import java.util.EnumSet;
058import java.util.List;
059import java.util.Map;
060import java.util.Map.Entry;
061import java.util.concurrent.Executor;
062import java.util.concurrent.TimeUnit;
063import java.util.concurrent.TimeoutException;
064import java.util.logging.Level;
065
066/**
067 * A manager for monitoring and controlling a set of {@linkplain Service services}. This class
068 * provides methods for {@linkplain #startAsync() starting}, {@linkplain #stopAsync() stopping} and
069 * {@linkplain #servicesByState inspecting} a collection of {@linkplain Service services}.
070 * Additionally, users can monitor state transitions with the {@linkplain Listener listener}
071 * mechanism.
072 *
073 * <p>While it is recommended that service lifecycles be managed via this class, state transitions
074 * initiated via other mechanisms do not impact the correctness of its methods. For example, if the
075 * services are started by some mechanism besides {@link #startAsync}, the listeners will be invoked
076 * when appropriate and {@link #awaitHealthy} will still work as expected.
077 *
078 * <p>Here is a simple example of how to use a {@code ServiceManager} to start a server.
079 *
080 * <pre>{@code
081 * class Server {
082 *   public static void main(String[] args) {
083 *     Set<Service> services = ...;
084 *     ServiceManager manager = new ServiceManager(services);
085 *     manager.addListener(new Listener() {
086 *         public void stopped() {}
087 *         public void healthy() {
088 *           // Services have been initialized and are healthy, start accepting requests...
089 *         }
090 *         public void failure(Service service) {
091 *           // Something failed, at this point we could log it, notify a load balancer, or take
092 *           // some other action.  For now we will just exit.
093 *           System.exit(1);
094 *         }
095 *       },
096 *       MoreExecutors.directExecutor());
097 *
098 *     Runtime.getRuntime().addShutdownHook(new Thread() {
099 *       public void run() {
100 *         // Give the services 5 seconds to stop to ensure that we are responsive to shutdown
101 *         // requests.
102 *         try {
103 *           manager.stopAsync().awaitStopped(5, TimeUnit.SECONDS);
104 *         } catch (TimeoutException timeout) {
105 *           // stopping timed out
106 *         }
107 *       }
108 *     });
109 *     manager.startAsync();  // start all the services asynchronously
110 *   }
111 * }
112 * }</pre>
113 *
114 * <p>This class uses the ServiceManager's methods to start all of its services, to respond to
115 * service failure and to ensure that when the JVM is shutting down all the services are stopped.
116 *
117 * @author Luke Sandberg
118 * @since 14.0
119 */
120@J2ktIncompatible
121@GwtIncompatible
122@ElementTypesAreNonnullByDefault
123public final class ServiceManager implements ServiceManagerBridge {
124  private static final LazyLogger logger = new LazyLogger(ServiceManager.class);
125  private static final ListenerCallQueue.Event<Listener> HEALTHY_EVENT =
126      new ListenerCallQueue.Event<Listener>() {
127        @Override
128        public void call(Listener listener) {
129          listener.healthy();
130        }
131
132        @Override
133        public String toString() {
134          return "healthy()";
135        }
136      };
137  private static final ListenerCallQueue.Event<Listener> STOPPED_EVENT =
138      new ListenerCallQueue.Event<Listener>() {
139        @Override
140        public void call(Listener listener) {
141          listener.stopped();
142        }
143
144        @Override
145        public String toString() {
146          return "stopped()";
147        }
148      };
149
150  /**
151   * A listener for the aggregate state changes of the services that are under management. Users
152   * that need to listen to more fine-grained events (such as when each particular {@linkplain
153   * Service service} starts, or terminates), should attach {@linkplain Service.Listener service
154   * listeners} to each individual service.
155   *
156   * @author Luke Sandberg
157   * @since 15.0 (present as an interface in 14.0)
158   */
159  public abstract static class Listener {
160    /**
161     * Called when the service initially becomes healthy.
162     *
163     * <p>This will be called at most once after all the services have entered the {@linkplain
164     * State#RUNNING running} state. If any services fail during start up or {@linkplain
165     * State#FAILED fail}/{@linkplain State#TERMINATED terminate} before all other services have
166     * started {@linkplain State#RUNNING running} then this method will not be called.
167     */
168    public void healthy() {}
169
170    /**
171     * Called when the all of the component services have reached a terminal state, either
172     * {@linkplain State#TERMINATED terminated} or {@linkplain State#FAILED failed}.
173     */
174    public void stopped() {}
175
176    /**
177     * Called when a component service has {@linkplain State#FAILED failed}.
178     *
179     * @param service The service that failed.
180     */
181    public void failure(Service service) {}
182  }
183
184  /**
185   * An encapsulation of all of the state that is accessed by the {@linkplain ServiceListener
186   * service listeners}. This is extracted into its own object so that {@link ServiceListener} could
187   * be made {@code static} and its instances can be safely constructed and added in the {@link
188   * ServiceManager} constructor without having to close over the partially constructed {@link
189   * ServiceManager} instance (i.e. avoid leaking a pointer to {@code this}).
190   */
191  private final ServiceManagerState state;
192
193  private final ImmutableList<Service> services;
194
195  /**
196   * Constructs a new instance for managing the given services.
197   *
198   * @param services The services to manage
199   * @throws IllegalArgumentException if not all services are {@linkplain State#NEW new} or if there
200   *     are any duplicate services.
201   */
202  public ServiceManager(Iterable<? extends Service> services) {
203    ImmutableList<Service> copy = ImmutableList.copyOf(services);
204    if (copy.isEmpty()) {
205      // Having no services causes the manager to behave strangely. Notably, listeners are never
206      // fired. To avoid this we substitute a placeholder service.
207      logger
208          .get()
209          .log(
210              Level.WARNING,
211              "ServiceManager configured with no services.  Is your application configured"
212                  + " properly?",
213              new EmptyServiceManagerWarning());
214      copy = ImmutableList.<Service>of(new NoOpService());
215    }
216    this.state = new ServiceManagerState(copy);
217    this.services = copy;
218    WeakReference<ServiceManagerState> stateReference = new WeakReference<>(state);
219    for (Service service : copy) {
220      service.addListener(new ServiceListener(service, stateReference), directExecutor());
221      // We check the state after adding the listener as a way to ensure that our listener was added
222      // to a NEW service.
223      checkArgument(service.state() == NEW, "Can only manage NEW services, %s", service);
224    }
225    // We have installed all of our listeners and after this point any state transition should be
226    // correct.
227    this.state.markReady();
228  }
229
230  /**
231   * Registers a {@link Listener} to be {@linkplain Executor#execute executed} on the given
232   * executor. The listener will not have previous state changes replayed, so it is suggested that
233   * listeners are added before any of the managed services are {@linkplain Service#startAsync
234   * started}.
235   *
236   * <p>{@code addListener} guarantees execution ordering across calls to a given listener but not
237   * across calls to multiple listeners. Specifically, a given listener will have its callbacks
238   * invoked in the same order as the underlying service enters those states. Additionally, at most
239   * one of the listener's callbacks will execute at once. However, multiple listeners' callbacks
240   * may execute concurrently, and listeners may execute in an order different from the one in which
241   * they were registered.
242   *
243   * <p>RuntimeExceptions thrown by a listener will be caught and logged. Any exception thrown
244   * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException}) will be caught and
245   * logged.
246   *
247   * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See
248   * the discussion in the {@link ListenableFuture#addListener ListenableFuture.addListener}
249   * documentation.
250   *
251   * @param listener the listener to run when the manager changes state
252   * @param executor the executor in which the listeners callback methods will be run.
253   */
254  public void addListener(Listener listener, Executor executor) {
255    state.addListener(listener, executor);
256  }
257
258  /**
259   * Initiates service {@linkplain Service#startAsync startup} on all the services being managed. It
260   * is only valid to call this method if all of the services are {@linkplain State#NEW new}.
261   *
262   * @return this
263   * @throws IllegalStateException if any of the Services are not {@link State#NEW new} when the
264   *     method is called.
265   */
266  @CanIgnoreReturnValue
267  public ServiceManager startAsync() {
268    for (Service service : services) {
269      checkState(service.state() == NEW, "Not all services are NEW, cannot start %s", this);
270    }
271    for (Service service : services) {
272      try {
273        state.tryStartTiming(service);
274        service.startAsync();
275      } catch (IllegalStateException e) {
276        // This can happen if the service has already been started or stopped (e.g. by another
277        // service or listener). Our contract says it is safe to call this method if
278        // all services were NEW when it was called, and this has already been verified above, so we
279        // don't propagate the exception.
280        logger.get().log(Level.WARNING, "Unable to start Service " + service, e);
281      }
282    }
283    return this;
284  }
285
286  /**
287   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy}. The manager
288   * will become healthy after all the component services have reached the {@linkplain State#RUNNING
289   * running} state.
290   *
291   * @throws IllegalStateException if the service manager reaches a state from which it cannot
292   *     become {@linkplain #isHealthy() healthy}.
293   */
294  public void awaitHealthy() {
295    state.awaitHealthy();
296  }
297
298  /**
299   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy} for no more
300   * than the given time. The manager will become healthy after all the component services have
301   * reached the {@linkplain State#RUNNING running} state.
302   *
303   * @param timeout the maximum time to wait
304   * @param unit the time unit of the timeout argument
305   * @throws TimeoutException if not all of the services have finished starting within the deadline
306   * @throws IllegalStateException if the service manager reaches a state from which it cannot
307   *     become {@linkplain #isHealthy() healthy}.
308   */
309  @SuppressWarnings("GoodTime") // should accept a java.time.Duration
310  public void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException {
311    state.awaitHealthy(timeout, unit);
312  }
313
314  /**
315   * Initiates service {@linkplain Service#stopAsync shutdown} if necessary on all the services
316   * being managed.
317   *
318   * @return this
319   */
320  @CanIgnoreReturnValue
321  public ServiceManager stopAsync() {
322    for (Service service : services) {
323      service.stopAsync();
324    }
325    return this;
326  }
327
328  /**
329   * Waits for the all the services to reach a terminal state. After this method returns all
330   * services will either be {@linkplain Service.State#TERMINATED terminated} or {@linkplain
331   * Service.State#FAILED failed}.
332   */
333  public void awaitStopped() {
334    state.awaitStopped();
335  }
336
337  /**
338   * Waits for the all the services to reach a terminal state for no more than the given time. After
339   * this method returns all services will either be {@linkplain Service.State#TERMINATED
340   * terminated} or {@linkplain Service.State#FAILED failed}.
341   *
342   * @param timeout the maximum time to wait
343   * @param unit the time unit of the timeout argument
344   * @throws TimeoutException if not all of the services have stopped within the deadline
345   */
346  @SuppressWarnings("GoodTime") // should accept a java.time.Duration
347  public void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException {
348    state.awaitStopped(timeout, unit);
349  }
350
351  /**
352   * Returns true if all services are currently in the {@linkplain State#RUNNING running} state.
353   *
354   * <p>Users who want more detailed information should use the {@link #servicesByState} method to
355   * get detailed information about which services are not running.
356   */
357  public boolean isHealthy() {
358    for (Service service : services) {
359      if (!service.isRunning()) {
360        return false;
361      }
362    }
363    return true;
364  }
365
366  /**
367   * Provides a snapshot of the current state of all the services under management.
368   *
369   * <p>N.B. This snapshot is guaranteed to be consistent, i.e. the set of states returned will
370   * correspond to a point in time view of the services.
371   *
372   * @since 29.0 (present with return type {@code ImmutableMultimap} since 14.0)
373   */
374  @Override
375  public ImmutableSetMultimap<State, Service> servicesByState() {
376    return state.servicesByState();
377  }
378
379  /**
380   * Returns the service load times. This value will only return startup times for services that
381   * have finished starting.
382   *
383   * @return Map of services and their corresponding startup time in millis, the map entries will be
384   *     ordered by startup time.
385   */
386  public ImmutableMap<Service, Long> startupTimes() {
387    return state.startupTimes();
388  }
389
390  @Override
391  public String toString() {
392    return MoreObjects.toStringHelper(ServiceManager.class)
393        .add("services", Collections2.filter(services, not(instanceOf(NoOpService.class))))
394        .toString();
395  }
396
397  /**
398   * An encapsulation of all the mutable state of the {@link ServiceManager} that needs to be
399   * accessed by instances of {@link ServiceListener}.
400   */
401  private static final class ServiceManagerState {
402    final Monitor monitor = new Monitor();
403
404    @GuardedBy("monitor")
405    final SetMultimap<State, Service> servicesByState =
406        MultimapBuilder.enumKeys(State.class).linkedHashSetValues().build();
407
408    @GuardedBy("monitor")
409    final Multiset<State> states = servicesByState.keys();
410
411    @GuardedBy("monitor")
412    final Map<Service, Stopwatch> startupTimers = Maps.newIdentityHashMap();
413
414    /**
415     * These two booleans are used to mark the state as ready to start.
416     *
417     * <p>{@link #ready}: is set by {@link #markReady} to indicate that all listeners have been
418     * correctly installed
419     *
420     * <p>{@link #transitioned}: is set by {@link #transitionService} to indicate that some
421     * transition has been performed.
422     *
423     * <p>Together, they allow us to enforce that all services have their listeners installed prior
424     * to any service performing a transition, then we can fail in the ServiceManager constructor
425     * rather than in a Service.Listener callback.
426     */
427    @GuardedBy("monitor")
428    boolean ready;
429
430    @GuardedBy("monitor")
431    boolean transitioned;
432
433    final int numberOfServices;
434
435    /**
436     * Controls how long to wait for all the services to either become healthy or reach a state from
437     * which it is guaranteed that it can never become healthy.
438     */
439    final Monitor.Guard awaitHealthGuard = new AwaitHealthGuard();
440
441    @WeakOuter
442    final class AwaitHealthGuard extends Monitor.Guard {
443      AwaitHealthGuard() {
444        super(ServiceManagerState.this.monitor);
445      }
446
447      @Override
448      @GuardedBy("ServiceManagerState.this.monitor")
449      public boolean isSatisfied() {
450        // All services have started or some service has terminated/failed.
451        return states.count(RUNNING) == numberOfServices
452            || states.contains(STOPPING)
453            || states.contains(TERMINATED)
454            || states.contains(FAILED);
455      }
456    }
457
458    /** Controls how long to wait for all services to reach a terminal state. */
459    final Monitor.Guard stoppedGuard = new StoppedGuard();
460
461    @WeakOuter
462    final class StoppedGuard extends Monitor.Guard {
463      StoppedGuard() {
464        super(ServiceManagerState.this.monitor);
465      }
466
467      @Override
468      @GuardedBy("ServiceManagerState.this.monitor")
469      public boolean isSatisfied() {
470        return states.count(TERMINATED) + states.count(FAILED) == numberOfServices;
471      }
472    }
473
474    /** The listeners to notify during a state transition. */
475    final ListenerCallQueue<Listener> listeners = new ListenerCallQueue<>();
476
477    /**
478     * It is implicitly assumed that all the services are NEW and that they will all remain NEW
479     * until all the Listeners are installed and {@link #markReady()} is called. It is our caller's
480     * responsibility to only call {@link #markReady()} if all services were new at the time this
481     * method was called and when all the listeners were installed.
482     */
483    ServiceManagerState(ImmutableCollection<Service> services) {
484      this.numberOfServices = services.size();
485      servicesByState.putAll(NEW, services);
486    }
487
488    /**
489     * Attempts to start the timer immediately prior to the service being started via {@link
490     * Service#startAsync()}.
491     */
492    void tryStartTiming(Service service) {
493      monitor.enter();
494      try {
495        Stopwatch stopwatch = startupTimers.get(service);
496        if (stopwatch == null) {
497          startupTimers.put(service, Stopwatch.createStarted());
498        }
499      } finally {
500        monitor.leave();
501      }
502    }
503
504    /**
505     * Marks the {@link State} as ready to receive transitions. Returns true if no transitions have
506     * been observed yet.
507     */
508    void markReady() {
509      monitor.enter();
510      try {
511        if (!transitioned) {
512          // nothing has transitioned since construction, good.
513          ready = true;
514        } else {
515          // This should be an extremely rare race condition.
516          List<Service> servicesInBadStates = Lists.newArrayList();
517          for (Service service : servicesByState().values()) {
518            if (service.state() != NEW) {
519              servicesInBadStates.add(service);
520            }
521          }
522          throw new IllegalArgumentException(
523              "Services started transitioning asynchronously before "
524                  + "the ServiceManager was constructed: "
525                  + servicesInBadStates);
526        }
527      } finally {
528        monitor.leave();
529      }
530    }
531
532    void addListener(Listener listener, Executor executor) {
533      listeners.addListener(listener, executor);
534    }
535
536    void awaitHealthy() {
537      monitor.enterWhenUninterruptibly(awaitHealthGuard);
538      try {
539        checkHealthy();
540      } finally {
541        monitor.leave();
542      }
543    }
544
545    void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException {
546      monitor.enter();
547      try {
548        if (!monitor.waitForUninterruptibly(awaitHealthGuard, timeout, unit)) {
549          throw new TimeoutException(
550              "Timeout waiting for the services to become healthy. The "
551                  + "following services have not started: "
552                  + Multimaps.filterKeys(servicesByState, in(ImmutableSet.of(NEW, STARTING))));
553        }
554        checkHealthy();
555      } finally {
556        monitor.leave();
557      }
558    }
559
560    void awaitStopped() {
561      monitor.enterWhenUninterruptibly(stoppedGuard);
562      monitor.leave();
563    }
564
565    void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException {
566      monitor.enter();
567      try {
568        if (!monitor.waitForUninterruptibly(stoppedGuard, timeout, unit)) {
569          throw new TimeoutException(
570              "Timeout waiting for the services to stop. The following "
571                  + "services have not stopped: "
572                  + Multimaps.filterKeys(servicesByState, not(in(EnumSet.of(TERMINATED, FAILED)))));
573        }
574      } finally {
575        monitor.leave();
576      }
577    }
578
579    ImmutableSetMultimap<State, Service> servicesByState() {
580      ImmutableSetMultimap.Builder<State, Service> builder = ImmutableSetMultimap.builder();
581      monitor.enter();
582      try {
583        for (Entry<State, Service> entry : servicesByState.entries()) {
584          if (!(entry.getValue() instanceof NoOpService)) {
585            builder.put(entry);
586          }
587        }
588      } finally {
589        monitor.leave();
590      }
591      return builder.build();
592    }
593
594    ImmutableMap<Service, Long> startupTimes() {
595      List<Entry<Service, Long>> loadTimes;
596      monitor.enter();
597      try {
598        loadTimes = Lists.newArrayListWithCapacity(startupTimers.size());
599        // N.B. There will only be an entry in the map if the service has started
600        for (Entry<Service, Stopwatch> entry : startupTimers.entrySet()) {
601          Service service = entry.getKey();
602          Stopwatch stopwatch = entry.getValue();
603          if (!stopwatch.isRunning() && !(service instanceof NoOpService)) {
604            loadTimes.add(Maps.immutableEntry(service, stopwatch.elapsed(MILLISECONDS)));
605          }
606        }
607      } finally {
608        monitor.leave();
609      }
610      Collections.sort(
611          loadTimes,
612          Ordering.natural()
613              .onResultOf(
614                  new Function<Entry<Service, Long>, Long>() {
615                    @Override
616                    public Long apply(Entry<Service, Long> input) {
617                      return input.getValue();
618                    }
619                  }));
620      return ImmutableMap.copyOf(loadTimes);
621    }
622
623    /**
624     * Updates the state with the given service transition.
625     *
626     * <p>This method performs the main logic of ServiceManager in the following steps.
627     *
628     * <ol>
629     *   <li>Update the {@link #servicesByState()}
630     *   <li>Update the {@link #startupTimers}
631     *   <li>Based on the new state queue listeners to run
632     *   <li>Run the listeners (outside of the lock)
633     * </ol>
634     */
635    void transitionService(final Service service, State from, State to) {
636      checkNotNull(service);
637      checkArgument(from != to);
638      monitor.enter();
639      try {
640        transitioned = true;
641        if (!ready) {
642          return;
643        }
644        // Update state.
645        checkState(
646            servicesByState.remove(from, service),
647            "Service %s not at the expected location in the state map %s",
648            service,
649            from);
650        checkState(
651            servicesByState.put(to, service),
652            "Service %s in the state map unexpectedly at %s",
653            service,
654            to);
655        // Update the timer
656        Stopwatch stopwatch = startupTimers.get(service);
657        if (stopwatch == null) {
658          // This means the service was started by some means other than ServiceManager.startAsync
659          stopwatch = Stopwatch.createStarted();
660          startupTimers.put(service, stopwatch);
661        }
662        if (to.compareTo(RUNNING) >= 0 && stopwatch.isRunning()) {
663          // N.B. if we miss the STARTING event then we may never record a startup time.
664          stopwatch.stop();
665          if (!(service instanceof NoOpService)) {
666            logger.get().log(Level.FINE, "Started {0} in {1}.", new Object[] {service, stopwatch});
667          }
668        }
669        // Queue our listeners
670
671        // Did a service fail?
672        if (to == FAILED) {
673          enqueueFailedEvent(service);
674        }
675
676        if (states.count(RUNNING) == numberOfServices) {
677          // This means that the manager is currently healthy. N.B. If other threads call isHealthy
678          // they are not guaranteed to get 'true', because any service could fail right now.
679          enqueueHealthyEvent();
680        } else if (states.count(TERMINATED) + states.count(FAILED) == numberOfServices) {
681          enqueueStoppedEvent();
682        }
683      } finally {
684        monitor.leave();
685        // Run our executors outside of the lock
686        dispatchListenerEvents();
687      }
688    }
689
690    void enqueueStoppedEvent() {
691      listeners.enqueue(STOPPED_EVENT);
692    }
693
694    void enqueueHealthyEvent() {
695      listeners.enqueue(HEALTHY_EVENT);
696    }
697
698    void enqueueFailedEvent(final Service service) {
699      listeners.enqueue(
700          new ListenerCallQueue.Event<Listener>() {
701            @Override
702            public void call(Listener listener) {
703              listener.failure(service);
704            }
705
706            @Override
707            public String toString() {
708              return "failed({service=" + service + "})";
709            }
710          });
711    }
712
713    /** Attempts to execute all the listeners in {@link #listeners}. */
714    void dispatchListenerEvents() {
715      checkState(
716          !monitor.isOccupiedByCurrentThread(),
717          "It is incorrect to execute listeners with the monitor held.");
718      listeners.dispatch();
719    }
720
721    @GuardedBy("monitor")
722    void checkHealthy() {
723      if (states.count(RUNNING) != numberOfServices) {
724        IllegalStateException exception =
725            new IllegalStateException(
726                "Expected to be healthy after starting. The following services are not running: "
727                    + Multimaps.filterKeys(servicesByState, not(equalTo(RUNNING))));
728        throw exception;
729      }
730    }
731  }
732
733  /**
734   * A {@link Service} that wraps another service and times how long it takes for it to start and
735   * also calls the {@link ServiceManagerState#transitionService(Service, State, State)}, to record
736   * the state transitions.
737   */
738  private static final class ServiceListener extends Service.Listener {
739    final Service service;
740    // We store the state in a weak reference to ensure that if something went wrong while
741    // constructing the ServiceManager we don't pointlessly keep updating the state.
742    final WeakReference<ServiceManagerState> state;
743
744    ServiceListener(Service service, WeakReference<ServiceManagerState> state) {
745      this.service = service;
746      this.state = state;
747    }
748
749    @Override
750    public void starting() {
751      ServiceManagerState state = this.state.get();
752      if (state != null) {
753        state.transitionService(service, NEW, STARTING);
754        if (!(service instanceof NoOpService)) {
755          logger.get().log(Level.FINE, "Starting {0}.", service);
756        }
757      }
758    }
759
760    @Override
761    public void running() {
762      ServiceManagerState state = this.state.get();
763      if (state != null) {
764        state.transitionService(service, STARTING, RUNNING);
765      }
766    }
767
768    @Override
769    public void stopping(State from) {
770      ServiceManagerState state = this.state.get();
771      if (state != null) {
772        state.transitionService(service, from, STOPPING);
773      }
774    }
775
776    @Override
777    public void terminated(State from) {
778      ServiceManagerState state = this.state.get();
779      if (state != null) {
780        if (!(service instanceof NoOpService)) {
781          logger
782              .get()
783              .log(
784                  Level.FINE,
785                  "Service {0} has terminated. Previous state was: {1}",
786                  new Object[] {service, from});
787        }
788        state.transitionService(service, from, TERMINATED);
789      }
790    }
791
792    @Override
793    public void failed(State from, Throwable failure) {
794      ServiceManagerState state = this.state.get();
795      if (state != null) {
796        // Log before the transition, so that if the process exits in response to server failure,
797        // there is a higher likelihood that the cause will be in the logs.
798        boolean log = !(service instanceof NoOpService);
799        if (log) {
800          logger
801              .get()
802              .log(
803                  Level.SEVERE,
804                  "Service " + service + " has failed in the " + from + " state.",
805                  failure);
806        }
807        state.transitionService(service, from, FAILED);
808      }
809    }
810  }
811
812  /**
813   * A {@link Service} instance that does nothing. This is only useful as a placeholder to ensure
814   * that the {@link ServiceManager} functions properly even when it is managing no services.
815   *
816   * <p>The use of this class is considered an implementation detail of ServiceManager and as such
817   * it is excluded from {@link #servicesByState}, {@link #startupTimes}, {@link #toString} and all
818   * logging statements.
819   */
820  private static final class NoOpService extends AbstractService {
821    @Override
822    protected void doStart() {
823      notifyStarted();
824    }
825
826    @Override
827    protected void doStop() {
828      notifyStopped();
829    }
830  }
831
832  /** This is never thrown but only used for logging. */
833  private static final class EmptyServiceManagerWarning extends Throwable {}
834}