From 42cb05d5ff71e2126a35bfbc55376bda231cfc38 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 17 Jul 2018 18:50:01 +0200
Subject: [PATCH] execute: document what the different structures are for in
 comments

---
 src/core/execute.h | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/core/execute.h b/src/core/execute.h
index 81a118c5cd9..bc832eebf04 100644
--- a/src/core/execute.h
+++ b/src/core/execute.h
@@ -77,10 +77,11 @@ typedef enum ExecKeyringMode {
         _EXEC_KEYRING_MODE_INVALID = -1,
 } ExecKeyringMode;
 
+/* Contains start and exit information about an executed command.  */
 struct ExecStatus {
+        pid_t pid;
         dual_timestamp start_timestamp;
         dual_timestamp exit_timestamp;
-        pid_t pid;
         int code;     /* as in siginfo_t::si_code */
         int status;   /* as in sigingo_t::si_status */
 };
@@ -92,6 +93,7 @@ typedef enum ExecCommandFlags {
         EXEC_COMMAND_AMBIENT_MAGIC = 8,
 } ExecCommandFlags;
 
+/* Stores information about commands we execute. Covers both configuration settings as well as runtime data. */
 struct ExecCommand {
         char *path;
         char **argv;
@@ -100,13 +102,16 @@ struct ExecCommand {
         LIST_FIELDS(ExecCommand, command); /* useful for chaining commands */
 };
 
+/* Encapsulates certain aspects of the runtime environment that is to be shared between multiple otherwise separate
+ * invocations of commands. Specifically, this allows sharing of /tmp and /var/tmp data as well as network namespaces
+ * between invocations of commands. This is a reference counted object, with one reference taken by each currently
+ * active command invocation that wants to share this runtime. */
 struct ExecRuntime {
         int n_ref;
 
         Manager *manager;
 
-        /* unit id of the owner */
-        char *id;
+        char *id; /* Unit id of the owner */
 
         char *tmp_dir;
         char *var_tmp_dir;
@@ -131,6 +136,9 @@ typedef struct ExecDirectory {
         mode_t mode;
 } ExecDirectory;
 
+/* Encodes configuration parameters applied to invoked commands. Does not carry runtime data, but only configuration
+ * changes sourced from unit files and suchlike. ExecContext objects are usually embedded into Unit objects, and do not
+ * change after being loaded. */
 struct ExecContext {
         char **environment;
         char **environment_files;
@@ -291,6 +299,8 @@ typedef enum ExecFlags {
         EXEC_SET_WATCHDOG      = 1 << 11,
 } ExecFlags;
 
+/* Parameters for a specific invocation of a command. This structure is put together right before a command is
+ * executed. */
 struct ExecParameters {
         char **environment;
 
-- 
2.39.5