001/*
002 * Copyright (C) 2009 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.util.concurrent.Platform.restoreInterruptIfIsInterruptedException;
018
019import com.google.common.annotations.GwtIncompatible;
020import com.google.common.annotations.J2ktIncompatible;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import java.util.concurrent.Executor;
023import java.util.concurrent.TimeUnit;
024import java.util.concurrent.TimeoutException;
025import java.util.logging.Level;
026import java.util.logging.Logger;
027
028/**
029 * Base class for services that can implement {@link #startUp}, {@link #run} and {@link #shutDown}
030 * methods. This class uses a single thread to execute the service; consider {@link AbstractService}
031 * if you would like to manage any threading manually.
032 *
033 * @author Jesse Wilson
034 * @since 1.0
035 */
036@GwtIncompatible
037@J2ktIncompatible
038@ElementTypesAreNonnullByDefault
039public abstract class AbstractExecutionThreadService implements Service {
040  private static final Logger logger =
041      Logger.getLogger(AbstractExecutionThreadService.class.getName());
042
043  /* use AbstractService for state management */
044  private final Service delegate =
045      new AbstractService() {
046        @Override
047        protected final void doStart() {
048          Executor executor = MoreExecutors.renamingDecorator(executor(), () -> serviceName());
049          executor.execute(
050              () -> {
051                try {
052                  startUp();
053                  notifyStarted();
054                  // If stopAsync() is called while starting we may be in the STOPPING state in
055                  // which case we should skip right down to shutdown.
056                  if (isRunning()) {
057                    try {
058                      AbstractExecutionThreadService.this.run();
059                    } catch (Throwable t) {
060                      restoreInterruptIfIsInterruptedException(t);
061                      try {
062                        shutDown();
063                      } catch (Exception ignored) {
064                        restoreInterruptIfIsInterruptedException(ignored);
065                        // TODO(lukes): if guava ever moves to java7, this would be a good
066                        // candidate for a suppressed exception, or maybe we could generalize
067                        // Closer.Suppressor
068                        logger.log(
069                            Level.WARNING,
070                            "Error while attempting to shut down the service after failure.",
071                            ignored);
072                      }
073                      notifyFailed(t);
074                      return;
075                    }
076                  }
077
078                  shutDown();
079                  notifyStopped();
080                } catch (Throwable t) {
081                  restoreInterruptIfIsInterruptedException(t);
082                  notifyFailed(t);
083                }
084              });
085        }
086
087        @Override
088        protected void doStop() {
089          triggerShutdown();
090        }
091
092        @Override
093        public String toString() {
094          return AbstractExecutionThreadService.this.toString();
095        }
096      };
097
098  /** Constructor for use by subclasses. */
099  protected AbstractExecutionThreadService() {}
100
101  /**
102   * Start the service. This method is invoked on the execution thread.
103   *
104   * <p>By default this method does nothing.
105   */
106  protected void startUp() throws Exception {}
107
108  /**
109   * Run the service. This method is invoked on the execution thread. Implementations must respond
110   * to stop requests. You could poll for lifecycle changes in a work loop:
111   *
112   * <pre>
113   *   public void run() {
114   *     while ({@link #isRunning()}) {
115   *       // perform a unit of work
116   *     }
117   *   }
118   * </pre>
119   *
120   * <p>...or you could respond to stop requests by implementing {@link #triggerShutdown()}, which
121   * should cause {@link #run()} to return.
122   */
123  protected abstract void run() throws Exception;
124
125  /**
126   * Stop the service. This method is invoked on the execution thread.
127   *
128   * <p>By default this method does nothing.
129   */
130  // TODO: consider supporting a TearDownTestCase-like API
131  protected void shutDown() throws Exception {}
132
133  /**
134   * Invoked to request the service to stop.
135   *
136   * <p>By default this method does nothing.
137   *
138   * <p>Currently, this method is invoked while holding a lock. If an implementation of this method
139   * blocks, it can prevent this service from changing state. If you need to performing a blocking
140   * operation in order to trigger shutdown, consider instead registering a listener and
141   * implementing {@code stopping}. Note, however, that {@code stopping} does not run at exactly the
142   * same times as {@code triggerShutdown}.
143   */
144  protected void triggerShutdown() {}
145
146  /**
147   * Returns the {@link Executor} that will be used to run this service. Subclasses may override
148   * this method to use a custom {@link Executor}, which may configure its worker thread with a
149   * specific name, thread group or priority. The returned executor's {@link
150   * Executor#execute(Runnable) execute()} method is called when this service is started, and should
151   * return promptly.
152   *
153   * <p>The default implementation returns a new {@link Executor} that sets the name of its threads
154   * to the string returned by {@link #serviceName}
155   */
156  protected Executor executor() {
157    return command -> MoreExecutors.newThread(serviceName(), command).start();
158  }
159
160  @Override
161  public String toString() {
162    return serviceName() + " [" + state() + "]";
163  }
164
165  @Override
166  public final boolean isRunning() {
167    return delegate.isRunning();
168  }
169
170  @Override
171  public final State state() {
172    return delegate.state();
173  }
174
175  /** @since 13.0 */
176  @Override
177  public final void addListener(Listener listener, Executor executor) {
178    delegate.addListener(listener, executor);
179  }
180
181  /** @since 14.0 */
182  @Override
183  public final Throwable failureCause() {
184    return delegate.failureCause();
185  }
186
187  /** @since 15.0 */
188  @CanIgnoreReturnValue
189  @Override
190  public final Service startAsync() {
191    delegate.startAsync();
192    return this;
193  }
194
195  /** @since 15.0 */
196  @CanIgnoreReturnValue
197  @Override
198  public final Service stopAsync() {
199    delegate.stopAsync();
200    return this;
201  }
202
203  /** @since 15.0 */
204  @Override
205  public final void awaitRunning() {
206    delegate.awaitRunning();
207  }
208
209  /** @since 15.0 */
210  @Override
211  public final void awaitRunning(long timeout, TimeUnit unit) throws TimeoutException {
212    delegate.awaitRunning(timeout, unit);
213  }
214
215  /** @since 15.0 */
216  @Override
217  public final void awaitTerminated() {
218    delegate.awaitTerminated();
219  }
220
221  /** @since 15.0 */
222  @Override
223  public final void awaitTerminated(long timeout, TimeUnit unit) throws TimeoutException {
224    delegate.awaitTerminated(timeout, unit);
225  }
226
227  /**
228   * Returns the name of this service. {@link AbstractExecutionThreadService} may include the name
229   * in debugging output.
230   *
231   * <p>Subclasses may override this method.
232   *
233   * @since 14.0 (present in 10.0 as getServiceName)
234   */
235  protected String serviceName() {
236    return getClass().getSimpleName();
237  }
238}