001 /*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.util.concurrent;
018
019 import com.google.common.annotations.Beta;
020 import com.google.common.base.Preconditions;
021 import com.google.common.base.Throwables;
022
023 import java.util.concurrent.Callable;
024 import java.util.concurrent.Executor;
025 import java.util.concurrent.Executors;
026 import java.util.concurrent.Future;
027 import java.util.concurrent.ScheduledExecutorService;
028 import java.util.concurrent.TimeUnit;
029 import java.util.concurrent.locks.ReentrantLock;
030 import java.util.logging.Level;
031 import java.util.logging.Logger;
032
033 import javax.annotation.concurrent.GuardedBy;
034
035 /**
036 * Base class for services that can implement {@link #startUp} and {@link #shutDown} but while in
037 * the "running" state need to perform a periodic task. Subclasses can implement {@link #startUp},
038 * {@link #shutDown} and also a {@link #runOneIteration} method that will be executed periodically.
039 *
040 * <p>This class uses the {@link ScheduledExecutorService} returned from {@link #executor} to run
041 * the {@link #startUp} and {@link #shutDown} methods and also uses that service to schedule the
042 * {@link #runOneIteration} that will be executed periodically as specified by its
043 * {@link Scheduler}. When this service is asked to stop via {@link #stop} or {@link #stopAndWait},
044 * it will cancel the periodic task (but not interrupt it) and wait for it to stop before running
045 * the {@link #shutDown} method.
046 *
047 * <p>Subclasses are guaranteed that the life cycle methods ({@link #runOneIteration}, {@link
048 * #startUp} and {@link #shutDown}) will never run concurrently. Notably, if any execution of {@link
049 * #runOneIteration} takes longer than its schedule defines, then subsequent executions may start
050 * late. Also, all life cycle methods are executed with a lock held, so subclasses can safely
051 * modify shared state without additional synchronization necessary for visibility to later
052 * executions of the life cycle methods.
053 *
054 * <h3>Usage Example</h3>
055 *
056 * Here is a sketch of a service which crawls a website and uses the scheduling capabilities to
057 * rate limit itself. <pre> {@code
058 * class CrawlingService extends AbstractScheduledService {
059 * private Set<Uri> visited;
060 * private Queue<Uri> toCrawl;
061 * protected void startUp() throws Exception {
062 * toCrawl = readStartingUris();
063 * }
064 *
065 * protected void runOneIteration() throws Exception {
066 * Uri uri = toCrawl.remove();
067 * Collection<Uri> newUris = crawl(uri);
068 * visited.add(uri);
069 * for (Uri newUri : newUris) {
070 * if (!visited.contains(newUri)) { toCrawl.add(newUri); }
071 * }
072 * }
073 *
074 * protected void shutDown() throws Exception {
075 * saveUris(toCrawl);
076 * }
077 *
078 * protected Scheduler scheduler() {
079 * return Scheduler.newFixedRateSchedule(0, 1, TimeUnit.SECONDS);
080 * }
081 * }}</pre>
082 *
083 * This class uses the life cycle methods to read in a list of starting URIs and save the set of
084 * outstanding URIs when shutting down. Also, it takes advantage of the scheduling functionality to
085 * rate limit the number of queries we perform.
086 *
087 * @author Luke Sandberg
088 * @since 11.0
089 */
090 @Beta
091 public abstract class AbstractScheduledService implements Service {
092 private static final Logger logger = Logger.getLogger(AbstractScheduledService.class.getName());
093
094 /**
095 * A scheduler defines the policy for how the {@link AbstractScheduledService} should run its
096 * task.
097 *
098 * <p>Consider using the {@link #newFixedDelaySchedule} and {@link #newFixedRateSchedule} factory
099 * methods, these provide {@link Scheduler} instances for the common use case of running the
100 * service with a fixed schedule. If more flexibility is needed then consider subclassing the
101 * {@link CustomScheduler} abstract class in preference to creating your own {@link Scheduler}
102 * implementation.
103 *
104 * @author Luke Sandberg
105 * @since 11.0
106 */
107 public abstract static class Scheduler {
108 /**
109 * Returns a {@link Scheduler} that schedules the task using the
110 * {@link ScheduledExecutorService#scheduleWithFixedDelay} method.
111 *
112 * @param initialDelay the time to delay first execution
113 * @param delay the delay between the termination of one execution and the commencement of the
114 * next
115 * @param unit the time unit of the initialDelay and delay parameters
116 */
117 public static Scheduler newFixedDelaySchedule(final long initialDelay, final long delay,
118 final TimeUnit unit) {
119 return new Scheduler() {
120 @Override
121 public Future<?> schedule(AbstractService service, ScheduledExecutorService executor,
122 Runnable task) {
123 return executor.scheduleWithFixedDelay(task, initialDelay, delay, unit);
124 }
125 };
126 }
127
128 /**
129 * Returns a {@link Scheduler} that schedules the task using the
130 * {@link ScheduledExecutorService#scheduleAtFixedRate} method.
131 *
132 * @param initialDelay the time to delay first execution
133 * @param period the period between successive executions of the task
134 * @param unit the time unit of the initialDelay and period parameters
135 */
136 public static Scheduler newFixedRateSchedule(final long initialDelay, final long period,
137 final TimeUnit unit) {
138 return new Scheduler() {
139 @Override
140 public Future<?> schedule(AbstractService service, ScheduledExecutorService executor,
141 Runnable task) {
142 return executor.scheduleAtFixedRate(task, initialDelay, period, unit);
143 }
144 };
145 }
146
147 /** Schedules the task to run on the provided executor on behalf of the service. */
148 abstract Future<?> schedule(AbstractService service, ScheduledExecutorService executor,
149 Runnable runnable);
150
151 private Scheduler() {}
152 }
153
154 /* use AbstractService for state management */
155 private final AbstractService delegate = new AbstractService() {
156
157 // A handle to the running task so that we can stop it when a shutdown has been requested.
158 // These two fields are volatile because their values will be accessed from multiple threads.
159 private volatile Future<?> runningTask;
160 private volatile ScheduledExecutorService executorService;
161
162 // This lock protects the task so we can ensure that none of the template methods (startUp,
163 // shutDown or runOneIteration) run concurrently with one another.
164 private final ReentrantLock lock = new ReentrantLock();
165
166 private final Runnable task = new Runnable() {
167 @Override public void run() {
168 lock.lock();
169 try {
170 AbstractScheduledService.this.runOneIteration();
171 } catch (Throwable t) {
172 try {
173 shutDown();
174 } catch (Exception ignored) {
175 logger.log(Level.WARNING,
176 "Error while attempting to shut down the service after failure.", ignored);
177 }
178 notifyFailed(t);
179 throw Throwables.propagate(t);
180 } finally {
181 lock.unlock();
182 }
183 }
184 };
185
186 @Override protected final void doStart() {
187 executorService = executor();
188 executorService.execute(new Runnable() {
189 @Override public void run() {
190 lock.lock();
191 try {
192 startUp();
193 runningTask = scheduler().schedule(delegate, executorService, task);
194 notifyStarted();
195 } catch (Throwable t) {
196 notifyFailed(t);
197 throw Throwables.propagate(t);
198 } finally {
199 lock.unlock();
200 }
201 }
202 });
203 }
204
205 @Override protected final void doStop() {
206 runningTask.cancel(false);
207 executorService.execute(new Runnable() {
208 @Override public void run() {
209 try {
210 lock.lock();
211 try {
212 if (state() != State.STOPPING) {
213 // This means that the state has changed since we were scheduled. This implies that
214 // an execution of runOneIteration has thrown an exception and we have transitioned
215 // to a failed state, also this means that shutDown has already been called, so we
216 // do not want to call it again.
217 return;
218 }
219 shutDown();
220 } finally {
221 lock.unlock();
222 }
223 notifyStopped();
224 } catch (Throwable t) {
225 notifyFailed(t);
226 throw Throwables.propagate(t);
227 }
228 }
229 });
230 }
231 };
232
233 /**
234 * Run one iteration of the scheduled task. If any invocation of this method throws an exception,
235 * the service will transition to the {@link Service.State#FAILED} state and this method will no
236 * longer be called.
237 */
238 protected abstract void runOneIteration() throws Exception;
239
240 /**
241 * Start the service.
242 *
243 * <p>By default this method does nothing.
244 */
245 protected void startUp() throws Exception {}
246
247 /**
248 * Stop the service. This is guaranteed not to run concurrently with {@link #runOneIteration}.
249 *
250 * <p>By default this method does nothing.
251 */
252 protected void shutDown() throws Exception {}
253
254 /**
255 * Returns the {@link Scheduler} object used to configure this service. This method will only be
256 * called once.
257 */
258 protected abstract Scheduler scheduler();
259
260 /**
261 * Returns the {@link ScheduledExecutorService} that will be used to execute the {@link #startUp},
262 * {@link #runOneIteration} and {@link #shutDown} methods. The executor will not be
263 * {@link ScheduledExecutorService#shutdown} when this service stops. Subclasses may override this
264 * method to use a custom {@link ScheduledExecutorService} instance.
265 *
266 * <p>By default this returns a new {@link ScheduledExecutorService} with a single thread thread
267 * pool. This method will only be called once.
268 */
269 protected ScheduledExecutorService executor() {
270 return Executors.newSingleThreadScheduledExecutor();
271 }
272
273 @Override public String toString() {
274 return getClass().getSimpleName() + " [" + state() + "]";
275 }
276
277 // We override instead of using ForwardingService so that these can be final.
278
279 @Override public final ListenableFuture<State> start() {
280 return delegate.start();
281 }
282
283 @Override public final State startAndWait() {
284 return delegate.startAndWait();
285 }
286
287 @Override public final boolean isRunning() {
288 return delegate.isRunning();
289 }
290
291 @Override public final State state() {
292 return delegate.state();
293 }
294
295 @Override public final ListenableFuture<State> stop() {
296 return delegate.stop();
297 }
298
299 @Override public final State stopAndWait() {
300 return delegate.stopAndWait();
301 }
302
303 @Override public final void addListener(Listener listener, Executor executor) {
304 delegate.addListener(listener, executor);
305 }
306
307 @Override public final Throwable failureCause() {
308 return delegate.failureCause();
309 }
310
311 /**
312 * A {@link Scheduler} that provides a convenient way for the {@link AbstractScheduledService} to
313 * use a dynamically changing schedule. After every execution of the task, assuming it hasn't
314 * been cancelled, the {@link #getNextSchedule} method will be called.
315 *
316 * @author Luke Sandberg
317 * @since 11.0
318 */
319 @Beta
320 public abstract static class CustomScheduler extends Scheduler {
321
322 /**
323 * A callable class that can reschedule itself using a {@link CustomScheduler}.
324 */
325 private class ReschedulableCallable extends ForwardingFuture<Void> implements Callable<Void> {
326
327 /** The underlying task. */
328 private final Runnable wrappedRunnable;
329
330 /** The executor on which this Callable will be scheduled. */
331 private final ScheduledExecutorService executor;
332
333 /**
334 * The service that is managing this callable. This is used so that failure can be
335 * reported properly.
336 */
337 private final AbstractService service;
338
339 /**
340 * This lock is used to ensure safe and correct cancellation, it ensures that a new task is
341 * not scheduled while a cancel is ongoing. Also it protects the currentFuture variable to
342 * ensure that it is assigned atomically with being scheduled.
343 */
344 private final ReentrantLock lock = new ReentrantLock();
345
346 /** The future that represents the next execution of this task.*/
347 @GuardedBy("lock")
348 private Future<Void> currentFuture;
349
350 ReschedulableCallable(AbstractService service, ScheduledExecutorService executor,
351 Runnable runnable) {
352 this.wrappedRunnable = runnable;
353 this.executor = executor;
354 this.service = service;
355 }
356
357 @Override
358 public Void call() throws Exception {
359 wrappedRunnable.run();
360 reschedule();
361 return null;
362 }
363
364 /**
365 * Atomically reschedules this task and assigns the new future to {@link #currentFuture}.
366 */
367 public void reschedule() {
368 // We reschedule ourselves with a lock held for two reasons. 1. we want to make sure that
369 // cancel calls cancel on the correct future. 2. we want to make sure that the assignment
370 // to currentFuture doesn't race with itself so that currentFuture is assigned in the
371 // correct order.
372 lock.lock();
373 try {
374 if (currentFuture == null || !currentFuture.isCancelled()) {
375 final Schedule schedule = CustomScheduler.this.getNextSchedule();
376 currentFuture = executor.schedule(this, schedule.delay, schedule.unit);
377 }
378 } catch (Throwable e) {
379 // If an exception is thrown by the subclass then we need to make sure that the service
380 // notices and transitions to the FAILED state. We do it by calling notifyFailed directly
381 // because the service does not monitor the state of the future so if the exception is not
382 // caught and forwarded to the service the task would stop executing but the service would
383 // have no idea.
384 service.notifyFailed(e);
385 } finally {
386 lock.unlock();
387 }
388 }
389
390 // N.B. Only protect cancel and isCancelled because those are the only methods that are
391 // invoked by the AbstractScheduledService.
392 @Override
393 public boolean cancel(boolean mayInterruptIfRunning) {
394 // Ensure that a task cannot be rescheduled while a cancel is ongoing.
395 lock.lock();
396 try {
397 return currentFuture.cancel(mayInterruptIfRunning);
398 } finally {
399 lock.unlock();
400 }
401 }
402
403 @Override
404 protected Future<Void> delegate() {
405 throw new UnsupportedOperationException("Only cancel is supported by this future");
406 }
407 }
408
409 @Override
410 final Future<?> schedule(AbstractService service, ScheduledExecutorService executor,
411 Runnable runnable) {
412 ReschedulableCallable task = new ReschedulableCallable(service, executor, runnable);
413 task.reschedule();
414 return task;
415 }
416
417 /**
418 * A value object that represents an absolute delay until a task should be invoked.
419 *
420 * @author Luke Sandberg
421 * @since 11.0
422 */
423 @Beta
424 protected static final class Schedule {
425
426 private final long delay;
427 private final TimeUnit unit;
428
429 /**
430 * @param delay the time from now to delay execution
431 * @param unit the time unit of the delay parameter
432 */
433 public Schedule(long delay, TimeUnit unit) {
434 this.delay = delay;
435 this.unit = Preconditions.checkNotNull(unit);
436 }
437 }
438
439 /**
440 * Calculates the time at which to next invoke the task.
441 *
442 * <p>This is guaranteed to be called immediately after the task has completed an iteration and
443 * on the same thread as the previous execution of {@link
444 * AbstractScheduledService#runOneIteration}.
445 *
446 * @return a schedule that defines the delay before the next execution.
447 */
448 protected abstract Schedule getNextSchedule() throws Exception;
449 }
450 }