Documenting the self-restarting process

README.markdown

@@ -65,6 +65,17 @@ The success or failure of these operations will be recorded in the event log.
 
 The `<download>` element in the configuration file also provides an useful building block for a self updating services.
 
+Restarting service from itself
+------------------------------
+To support self-restarting services, winsw exposes `WINSW_EXECUTABLE` environment variable into the forked process, which refers to the full path of `winsw.exe` that's managing the service.
+To restart the service from within, execute `$WINSW_EXECUTABLE restart!`. Note that you are invoking `restart!` command, not `restart` command. This hidden command is a flavor of the `restart` operation,
+except that winsw creates another winsw process in a separate process group, and restarts the service from there.
+
+This additional indirection is necessary, because Windows Service Control Manager (SCM) will kill child processes recursively when it stops the service. SCM doesn't provide restart operation
+as an atomic operation either, so winsw implements restart by a sequence of stop and start. The 2nd winsw process in a separate process group ensures that winsw can survive this massacre to
+execute the start call.
+
+
 Logging
 -------
 Winsw supports several different ways to capture stdout and stderr from the process you launch.