From dc46627fea51a6c5fc7a0f1506c6e85f75a3a15e Mon Sep 17 00:00:00 2001 From: Jesse Wilson Date: Fri, 10 Apr 2020 08:16:41 -0700 Subject: [PATCH] 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 --- .../util/concurrent/AbstractExecutionThreadService.java | 8 +++++++- .../common/util/concurrent/AbstractIdleService.java | 2 -- .../common/util/concurrent/AbstractScheduledService.java | 4 ---- .../google/common/util/concurrent/AbstractService.java | 2 +- .../src/com/google/common/util/concurrent/Service.java | 6 +----- .../com/google/common/util/concurrent/ServiceManager.java | 4 +--- .../util/concurrent/AbstractExecutionThreadService.java | 8 +++++++- .../common/util/concurrent/AbstractIdleService.java | 2 -- .../common/util/concurrent/AbstractScheduledService.java | 4 ---- .../google/common/util/concurrent/AbstractService.java | 2 +- guava/src/com/google/common/util/concurrent/Service.java | 6 +----- .../com/google/common/util/concurrent/ServiceManager.java | 4 +--- 12 files changed, 20 insertions(+), 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 index f92200a93a3c..2bd392ca6df7 100644 --- 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. * *

By default this method does nothing. + * + *

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 index 4df45a3d3dd3..7416a9b655b2 100644 --- 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 index a303f68c1db4..70d4fb759aac 100644 --- 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 index 73bf2317290f..733bf3b77813 100644 --- 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 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 index 9cfb617b306a..2c6cdabd3ce0 100644 --- 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 index fa7293783b47..4f9ef13d8deb 100644 --- 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 index 6fcd4e12e20a..1bee501ca2be 100644 --- 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. * *

By default this method does nothing. + * + *

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 index d1187b5112bb..b49db7a3e2fc 100644 --- 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 index 5785741d0e71..a7a342ad5f6c 100644 --- 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 index 0ef75ded9248..f5d38edbb616 100644 --- 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 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 index b8ec15fc0746..3c4c47628dec 100644 --- 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 index 1748ca6972db..ccf0db9f531a 100644 --- 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());