init: add warning that `start` is not synchronous
Bug: 36571736
Bug: 37481363
Change-Id: I5d360cbb3635f00453a492ee4e3650fb80f390f5
diff --git a/init/README.md b/init/README.md
index 8cb1e52..1837868 100644
--- a/init/README.md
+++ b/init/README.md
@@ -276,7 +276,8 @@
`class_start <serviceclass>`
> Start all services of the specified class if they are
- not already running.
+ not already running. See the start entry for more information on
+ starting services.
`class_stop <serviceclass>`
> Stop and disable all services of the specified class if they are
@@ -401,6 +402,16 @@
`start <service>`
> Start a service running if it is not already running.
+ Note that this is _not_ synchronous, and even if it were, there is
+ no guarantee that the operating system's scheduler will execute the
+ service sufficiently to guarantee anything about the service's status.
+
+> This creates an important consequence that if the service offers
+ functionality to other services, such as providing a
+ communication channel, simply starting this service before those
+ services is _not_ sufficient to guarantee that the channel has
+ been set up before those services ask for it. There must be a
+ separate mechanism to make any such guarantees.
`stop <service>`
> Stop a service from running if it is currently running.