Remove @Beta from Service and ServiceManager.

This leaves `AbstractListeningExecutorService` as `@Beta`. Fixes #3806, #3418 Relevant to #2966 (I have tweaked Jesse's initial PR to leave `AbstractExecutionThreadService.triggerShutdown` and `AbstractService.doCancelStart` as `@Beta`, since we aren't sure we like the locking behavior of the former, and we've realized that `Listener.stopping` _might_ be a reasonable substitute for both.) RELNOTES=`util.concurrent`: Removed `@Beta` from `Service` and related classes. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=305878924
google · Apr 10, 2020 · dc46627 · dc46627
1 parent 9537f78
commit dc46627
Show file tree

Hide file tree

Showing 12 changed files with 20 additions and 32 deletions.
diff --git a/android/guava/src/com/google/common/util/concurrent/AbstractExecutionThreadService.java b/android/guava/src/com/google/common/util/concurrent/AbstractExecutionThreadService.java
@@ -32,7 +32,6 @@
  * @author Jesse Wilson
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractExecutionThreadService implements Service {
   private static final Logger logger =
@@ -140,7 +139,14 @@ protected void shutDown() throws Exception {}
    * Invoked to request the service to stop.
    *
    * <p>By default this method does nothing.
+   *
+   * <p>Currently, this method is invoked while holding a lock. If an implementation of this method
+   * blocks, it can prevent this service from changing state. If you need to performing a blocking
+   * operation in order to trigger shutdown, consider instead registering a listener and
+   * implementing {@code stopping}. Note, however, that {@code stopping} does not run at exactly the
+   * same times as {@code triggerShutdown}.
    */
+  @Beta
   protected void triggerShutdown() {}
 
   /**

diff --git a/android/guava/src/com/google/common/util/concurrent/AbstractIdleService.java b/android/guava/src/com/google/common/util/concurrent/AbstractIdleService.java
@@ -14,7 +14,6 @@
 
 package com.google.common.util.concurrent;
 
-import com.google.common.annotations.Beta;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.common.base.Supplier;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -31,7 +30,6 @@
  * @author Chris Nokleberg
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractIdleService implements Service {
 

diff --git a/android/guava/src/com/google/common/util/concurrent/AbstractScheduledService.java b/android/guava/src/com/google/common/util/concurrent/AbstractScheduledService.java
@@ -18,7 +18,6 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.util.concurrent.MoreExecutors.directExecutor;
 
-import com.google.common.annotations.Beta;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.common.base.Supplier;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -94,7 +93,6 @@
  * @author Luke Sandberg
  * @since 11.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractScheduledService implements Service {
   private static final Logger logger = Logger.getLogger(AbstractScheduledService.class.getName());
@@ -440,7 +438,6 @@ public final void awaitTerminated(long timeout, TimeUnit unit) throws TimeoutExc
    * @author Luke Sandberg
    * @since 11.0
    */
-  @Beta
   public abstract static class CustomScheduler extends Scheduler {
 
     /** A callable class that can reschedule itself using a {@link CustomScheduler}. */
@@ -567,7 +564,6 @@ final Future<?> schedule(
      * @author Luke Sandberg
      * @since 11.0
      */
-    @Beta
     protected static final class Schedule {
 
       private final long delay;

diff --git a/android/guava/src/com/google/common/util/concurrent/AbstractService.java b/android/guava/src/com/google/common/util/concurrent/AbstractService.java
@@ -47,7 +47,6 @@
  * @author Luke Sandberg
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractService implements Service {
   private static final ListenerCallQueue.Event<Listener> STARTING_EVENT =
@@ -235,6 +234,7 @@ protected AbstractService() {}
    *
    * @since 27.0
    */
+  @Beta
   @ForOverride
   protected void doCancelStart() {}
 

diff --git a/android/guava/src/com/google/common/util/concurrent/Service.java b/android/guava/src/com/google/common/util/concurrent/Service.java
@@ -14,10 +14,9 @@
 
 package com.google.common.util.concurrent;
 
-import com.google.common.annotations.Beta;
-import com.google.errorprone.annotations.DoNotMock;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.errorprone.annotations.DoNotMock;
 import java.util.concurrent.Executor;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
@@ -52,7 +51,6 @@
  * @author Luke Sandberg
  * @since 9.0 (in 1.0 as {@code com.google.common.base.Service})
  */
-@Beta
 @DoNotMock("Create an AbstractIdleService")
 @GwtIncompatible
 public interface Service {
@@ -175,7 +173,6 @@ public interface Service {
    *
    * @since 9.0 (in 1.0 as {@code com.google.common.base.Service.State})
    */
-  @Beta // should come out of Beta when Service does
   enum State {
     /** A service in this state is inactive. It does minimal work and consumes minimal resources. */
     NEW {
@@ -243,7 +240,6 @@ boolean isTerminal() {
    * @author Luke Sandberg
    * @since 15.0 (present as an interface in 13.0)
    */
-  @Beta // should come out of Beta when Service does
   abstract class Listener {
     /**
      * Called when the service transitions from {@linkplain State#NEW NEW} to {@linkplain

diff --git a/android/guava/src/com/google/common/util/concurrent/ServiceManager.java b/android/guava/src/com/google/common/util/concurrent/ServiceManager.java
@@ -118,7 +118,6 @@
  * @author Luke Sandberg
  * @since 14.0
  */
-@Beta
 @GwtIncompatible
 public final class ServiceManager implements ServiceManagerBridge {
   private static final Logger logger = Logger.getLogger(ServiceManager.class.getName());
@@ -156,7 +155,6 @@ public String toString() {
    * @author Luke Sandberg
    * @since 15.0 (present as an interface in 14.0)
    */
-  @Beta // Should come out of Beta when ServiceManager does
   public abstract static class Listener {
     /**
      * Called when the service initially becomes healthy.
@@ -275,7 +273,7 @@ public void addListener(Listener listener, Executor executor) {
    *     {@link ListenableFuture#addListener ListenableFuture.addListener}. This method is scheduled
    *     for deletion in October 2020.
    */
-  @Beta // currently redundant, but ensures we keep this @Beta when we gradate the class!
+  @Beta
   @Deprecated
   public void addListener(Listener listener) {
     state.addListener(listener, directExecutor());

diff --git a/guava/src/com/google/common/util/concurrent/AbstractExecutionThreadService.java b/guava/src/com/google/common/util/concurrent/AbstractExecutionThreadService.java
@@ -33,7 +33,6 @@
  * @author Jesse Wilson
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractExecutionThreadService implements Service {
   private static final Logger logger =
@@ -141,7 +140,14 @@ protected void shutDown() throws Exception {}
    * Invoked to request the service to stop.
    *
    * <p>By default this method does nothing.
+   *
+   * <p>Currently, this method is invoked while holding a lock. If an implementation of this method
+   * blocks, it can prevent this service from changing state. If you need to performing a blocking
+   * operation in order to trigger shutdown, consider instead registering a listener and
+   * implementing {@code stopping}. Note, however, that {@code stopping} does not run at exactly the
+   * same times as {@code triggerShutdown}.
    */
+  @Beta
   protected void triggerShutdown() {}
 
   /**

diff --git a/guava/src/com/google/common/util/concurrent/AbstractIdleService.java b/guava/src/com/google/common/util/concurrent/AbstractIdleService.java
@@ -14,7 +14,6 @@
 
 package com.google.common.util.concurrent;
 
-import com.google.common.annotations.Beta;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.common.base.Supplier;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -32,7 +31,6 @@
  * @author Chris Nokleberg
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractIdleService implements Service {
 

diff --git a/guava/src/com/google/common/util/concurrent/AbstractScheduledService.java b/guava/src/com/google/common/util/concurrent/AbstractScheduledService.java
@@ -19,7 +19,6 @@
 import static com.google.common.util.concurrent.Internal.toNanosSaturated;
 import static com.google.common.util.concurrent.MoreExecutors.directExecutor;
 
-import com.google.common.annotations.Beta;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.common.base.Supplier;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -96,7 +95,6 @@
  * @author Luke Sandberg
  * @since 11.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractScheduledService implements Service {
   private static final Logger logger = Logger.getLogger(AbstractScheduledService.class.getName());
@@ -481,7 +479,6 @@ public final void awaitTerminated(long timeout, TimeUnit unit) throws TimeoutExc
    * @author Luke Sandberg
    * @since 11.0
    */
-  @Beta
   public abstract static class CustomScheduler extends Scheduler {
 
     /** A callable class that can reschedule itself using a {@link CustomScheduler}. */
@@ -607,7 +604,6 @@ final Future<?> schedule(
      * @author Luke Sandberg
      * @since 11.0
      */
-    @Beta
     protected static final class Schedule {
 
       private final long delay;

diff --git a/guava/src/com/google/common/util/concurrent/AbstractService.java b/guava/src/com/google/common/util/concurrent/AbstractService.java
@@ -48,7 +48,6 @@
  * @author Luke Sandberg
  * @since 1.0
  */
-@Beta
 @GwtIncompatible
 public abstract class AbstractService implements Service {
   private static final ListenerCallQueue.Event<Listener> STARTING_EVENT =
@@ -236,6 +235,7 @@ protected AbstractService() {}
    *
    * @since 27.0
    */
+  @Beta
   @ForOverride
   protected void doCancelStart() {}
 

diff --git a/guava/src/com/google/common/util/concurrent/Service.java b/guava/src/com/google/common/util/concurrent/Service.java
@@ -16,10 +16,9 @@
 
 import static com.google.common.util.concurrent.Internal.toNanosSaturated;
 
-import com.google.common.annotations.Beta;
-import com.google.errorprone.annotations.DoNotMock;
 import com.google.common.annotations.GwtIncompatible;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.errorprone.annotations.DoNotMock;
 import java.time.Duration;
 import java.util.concurrent.Executor;
 import java.util.concurrent.TimeUnit;
@@ -55,7 +54,6 @@
  * @author Luke Sandberg
  * @since 9.0 (in 1.0 as {@code com.google.common.base.Service})
  */
-@Beta
 @DoNotMock("Create an AbstractIdleService")
 @GwtIncompatible
 public interface Service {
@@ -206,7 +204,6 @@ default void awaitTerminated(Duration timeout) throws TimeoutException {
    *
    * @since 9.0 (in 1.0 as {@code com.google.common.base.Service.State})
    */
-  @Beta // should come out of Beta when Service does
   enum State {
     /** A service in this state is inactive. It does minimal work and consumes minimal resources. */
     NEW {
@@ -274,7 +271,6 @@ boolean isTerminal() {
    * @author Luke Sandberg
    * @since 15.0 (present as an interface in 13.0)
    */
-  @Beta // should come out of Beta when Service does
   abstract class Listener {
     /**
      * Called when the service transitions from {@linkplain State#NEW NEW} to {@linkplain

diff --git a/guava/src/com/google/common/util/concurrent/ServiceManager.java b/guava/src/com/google/common/util/concurrent/ServiceManager.java
@@ -120,7 +120,6 @@
  * @author Luke Sandberg
  * @since 14.0
  */
-@Beta
 @GwtIncompatible
 public final class ServiceManager implements ServiceManagerBridge {
   private static final Logger logger = Logger.getLogger(ServiceManager.class.getName());
@@ -158,7 +157,6 @@ public String toString() {
    * @author Luke Sandberg
    * @since 15.0 (present as an interface in 14.0)
    */
-  @Beta // Should come out of Beta when ServiceManager does
   public abstract static class Listener {
     /**
      * Called when the service initially becomes healthy.
@@ -277,7 +275,7 @@ public void addListener(Listener listener, Executor executor) {
    *     {@link ListenableFuture#addListener ListenableFuture.addListener}. This method is scheduled
    *     for deletion in October 2020.
    */
-  @Beta // currently redundant, but ensures we keep this @Beta when we gradate the class!
+  @Beta
   @Deprecated
   public void addListener(Listener listener) {
     state.addListener(listener, directExecutor());