[CRIU] [PATCH 08/10] restore: Write comments about stages

[Pavel Emelyanov]

Describe what the tasks do during restore and what the
expectations at the sync points are.

Signed-off-by: Pavel Emelyanov <xemul at virtuozzo.com>
---
 criu/include/restorer.h | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/criu/include/restorer.h b/criu/include/restorer.h
index 307ee27..ebfd1bd 100644
--- a/criu/include/restorer.h
+++ b/criu/include/restorer.h
@@ -204,17 +204,47 @@ static inline unsigned long restorer_stack(struct restore_mem_zone *mz)
 }
 
 enum {
+	/*
+	 * Restore stages. The stage is started by criu process, then
+	 * confirmed by all tasks involved in it. Then criu does some
+	 * actions and starts the next stage.
+	 *
+	 * The first stated stage is CR_STATE_ROOT_TASK which is started
+	 * right before calling fork_with_pid() for the root_item.
+	 */
 	CR_STATE_FAIL		= -1,
-	CR_STATE_ROOT_TASK	= 0, /* is used for executing "setup-namespace" scripts */
 	/*
-	 * Need to wait a mount namespace which
-	 * will be used to clean up remap files.
+	 * Root task is created and does some pre-checks.
+	 * After the stage ACT_SETUP_NS scripts are performed.
+	 */
+	CR_STATE_ROOT_TASK	= 0,
+	/*
+	 * The prepare_namespace() is called.
+	 * After the stage criu opens root task's mntns and
+	 * calls ACT_POST_SETUP_NS scripts.
 	 */
 	CR_STATE_PREPARE_NAMESPACES,
+	/*
+	 * All tasks fork and call open_transport_socket().
+	 * Stage is needed to make sure they all have the socket.
+	 */
 	CR_STATE_FORKING,
+	/*
+	 * Main restore stage. By the end of it all tasks are
+	 * almost ready and what's left is:
+	 *   pick up zombies and helpers
+	 *   restore sigchild handlers used to detect restore errors
+	 *   restore credentials
+	 */
 	CR_STATE_RESTORE,
+	/*
+	 * Tasks restore sigchild handlers.
+	 * Stage is needed to synchronize the change in error
+	 * propagation via sigchild.
+	 */
 	CR_STATE_RESTORE_SIGCHLD,
 	/*
+	 * Final stage.
 	 * For security reason processes can be resumed only when all
 	 * credentials are restored. Otherwise someone can attach to a
 	 * process, which are not restored credentials yet and execute
-- 
2.1.4