Javadoc non-blocking service lifecycle methods

src/main/java/org/jboss/msc/service/LifecycleContext.java

@@ -63,8 +63,13 @@ public interface LifecycleContext extends Executor {
 
     /**
      * Execute a task asynchronously using the MSC task executor.
+     * <p>
+     * <strong>Note:</strong> This method should not be used for executing tasks that may block,
+     * particularly from within a service's {@link Service#start(StartContext)} or {@link Service#stop(StopContext)}
+     * methods. See {@link Service the Service class javadoc} for further details.
      *
      * @param command the command to execute
      */
+    @Override
     void execute(Runnable command);
 }

src/main/java/org/jboss/msc/service/Service.java

@@ -34,6 +34,32 @@
  * <p>
  * The value type specified by this service is used by default by consumers of this service, and should represent the
  * public interface of this service, which may or may not be the same as the implementing type of this service.
+ * <p>
+ * When writing MSC service implementations, your {@link #start(StartContext)} and {@link #stop(StopContext)}
+ * methods must never block.  This means these methods must not:
+ * <ul>
+ * <li>Use network connections</li>
+ * <li>Wait for network connections</li>
+ * <li>Sleep</li>
+ * <li>Wait on a condition</li>
+ * <li>Wait on a count down latch</li>
+ * <li>Call any method which may do any of the above</li>
+ * <li>Wait for termination of a thread pool or other service</li>
+ * <li>Wait for another service to change state</li>
+ * </ul>
+ *
+ * If your service start/stop does any of these things, you must use the asynchronous start/stop mechanism
+ * ({@link LifecycleContext#asynchronous()}) and do one of the following:
+ *
+ * <ul>
+ * <li>Initiate your task in start()/stop(), and utilize a callback (NIO, ThreadPoolExecutor.terminated(), etc.) to call
+ * {@link LifecycleContext#complete()} when your start/stop completes instead of blocking</li>
+ * <li>Delegate your blocking task to a thread pool ({@code Executor}) which calls {@link LifecycleContext#complete()}
+ * when done</li>
+ * <li>Use proper dependencies instead of explicitly waiting for services in your start/stop</li>
+ * </ul>
+ * <p>
+ * Note that using {@link LifecycleContext#execute(Runnable)} to execute the blocking task is also not permissible.
  *
  * @param <T> the type of value that this service provides; may be {@link Void}
  *
@@ -44,6 +70,9 @@ public interface Service<T> extends Value<T> {
     /**
      * Start the service.  Do not return until the service has been fully started, unless an asynchronous service
      * start is performed.  All injections will be complete before this method is called.
+     * <p>
+     * If the service start involves any activities that may block, the asynchronous mechanism
+     * provided by the {@code context} should be used. See the {@link Service class javadoc} for details.
      *
      * @param context the context which can be used to trigger an asynchronous service start
      * @throws StartException if the service could not be started for some reason
@@ -54,6 +83,9 @@ public interface Service<T> extends Value<T> {
      * Stop the service.  Do not return until the service has been fully stopped, unless an asynchronous service
      * stop is performed.  All injections will remain intact until the service is fully stopped.  This method should
      * not throw an exception.
+     * <p>
+     * If the service start involves any activities that may block, the asynchronous mechanism
+     * provided by the {@code context} should be used. See the {@link Service class javadoc} for details.
      *
      * @param context the context which can be used to trigger an asynchronous service stop
      */