From 86bbcf3277752cdfa861fbfae6fe4a22659e1c31 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Thu, 28 Jul 2022 23:17:42 -0500 Subject: [PATCH] Cleanup: Spelling mistakes, styling mistakes, and improve documentation about Time. The documentation about Time vs Epoch time is a bit confusing. Changes the sentences with the goal of improving the documentation. I may also end up moving the Time documentation to the FLL core documentation rather than have it be part of Controller. --- level_3/controller/documents/entry.txt | 11 +++++------ level_3/controller/documents/exit.txt | 4 ++-- level_3/controller/documents/packet.txt | 4 ++-- level_3/controller/documents/rule.txt | 4 ++-- level_3/controller/documents/time.txt | 5 +++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/level_3/controller/documents/entry.txt b/level_3/controller/documents/entry.txt index 555ed01..602cf78 100644 --- a/level_3/controller/documents/entry.txt +++ b/level_3/controller/documents/entry.txt @@ -82,12 +82,12 @@ Entry Documentation: For "ready", when "ready" create a PID file, display error on failure and then fail (does not check if PID file exists). - The "pid_file" setting\: - When "pid" is not disabed this represents the path to the PID file. + When "pid" is not disabled this represents the path to the PID file. If -p or --pid is passed to the controller program, then this value is ignored in favor of the value passed along the command line. - The "session" setting\: Represents the default way in which child processes are executed. - This default can be overriden by individual Rules. + This default can be overridden by individual Rules. For "new", Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a "controlling terminal"). For "same", Execute Rule processes in the same session where the process group is set to the parent process id. @@ -102,7 +102,7 @@ Entry Documentation: Represents the default timeouts for the Entry. See the "timeout" Action below for details. - - The "item" item Object\: + - The "main" item Object\: Each "item" supports the following Action Names: "consider", "execute", "failsafe", "freeze", "item", "kill", "pause", "reload", "restart", "ready", "resume", "start", "stop", and "timeout". Of those types, the following are considered a "rule" Action: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". @@ -115,7 +115,7 @@ Entry Documentation: - The "execute" Item Action\: Execute into the specified program. - On successfull execution, the controller program will no longer be running and will be replaced with the designated program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. This Item Action is only supported when operating in "program" mode. - The "failsafe" Item Action\: @@ -187,7 +187,6 @@ Entry Documentation: For "start", this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. For "stop", this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. If the second Content is not specified, then this disables the type (prevents the specified timeout action). - For "exit", this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal). In this case, a terminate signal is sent to all child processes. The "exit" timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running. @@ -211,7 +210,7 @@ Entry Rule Documentation: - "require": Designates that this Rule must succeed or trigger execution of failsafe. - "wait": Designates that this Rule will not execute until all other Actions before this (including "asynchronous" ones) finish executing (in a top-down manner). - The full path to the "rule" is relative to the settings, such that if the controller Rule settings are found in "/etc/controller/rules/", then for a directory called "[directory]" and a Rule base name of "[base_name]", the resulting path would be: "/etc/controller/rules/[directory]/[base_name].rule" + The full path to the "rule" is relative to the settings, such that if the controller Rule settings are found in "/etc/controller/rules/", then for a directory called "[directory]" and a Rule base name of "[base_name]", the resulting path would be: "/etc/controller/rules/[directory]/[base_name].rule". It is important to note that for any given "rule", execution within that "rule" may be internally asynchronous (even if the "rule" is synchronous). For example, a service that is often called a daemon will execute in the background. diff --git a/level_3/controller/documents/exit.txt b/level_3/controller/documents/exit.txt index 3dd2de1..0ac3123 100644 --- a/level_3/controller/documents/exit.txt +++ b/level_3/controller/documents/exit.txt @@ -12,7 +12,7 @@ Exit Documentation: An Exit is a special variation or subset of an Entry. - The "settings" Item Object\: - Represents settings and is not an "item" that can be executed. + Represents Exit settings and is not an "item" that can be executed. A number of settings are supported, but if this Item Object is not specified, then defaults are used. The following settings are available: "pid" and "show". @@ -68,7 +68,7 @@ Exit Documentation: - The "execute" Item Action\: Execute into the specified program. - On successfull execution, the controller program will no longer be running and will be replaced with the designated program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. This Item Action is only supported when operating in "program" mode. - The "failsafe" Item Action\: diff --git a/level_3/controller/documents/packet.txt b/level_3/controller/documents/packet.txt index 88c46b7..9e8eee3 100644 --- a/level_3/controller/documents/packet.txt +++ b/level_3/controller/documents/packet.txt @@ -42,7 +42,7 @@ Packet Documentation: The "at" condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock. The "in" condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started. - For these "time" conditions, different units of time should be supported, such as "seconds", "days", "years" as standard time, Time or UNIX Time (Epoch Time). + For these "time" conditions, different units of time should be supported, such as "seconds", "days", "years" as standard time, Time, or UNIX Time (Epoch Time). The normal "controller" payload commands are any valid Rule Action that performs some action. This does not include Actions that provide some setting or configuration (such as "with_pid"). @@ -70,4 +70,4 @@ Packet Documentation: The "kexec" is for booting into another kernel, which may effectively be the same as a "reboot" ("kexec" is currently neither supported nor implemented). The "reboot" is for rebooting the machine (currently not implemented). The "shutdown" is for shutting down the machine (currently not implemented). - These three commands are configurable to fire off based on conditions\: + These three commands are configurable to fire off based on conditions. diff --git a/level_3/controller/documents/rule.txt b/level_3/controller/documents/rule.txt index bf0c50e..892924d 100644 --- a/level_3/controller/documents/rule.txt +++ b/level_3/controller/documents/rule.txt @@ -56,7 +56,7 @@ Rule Documentation: - The "limit" setting\: The first parameter must be one of: "as", "core", "cpu", "data", "fsize", "locks", "memlock", "msgqueue", "nice", "nofile", "nproc", "rss", "rtprio", "rttime", "sigpending", or "stack". - The second parameter repesents the soft limit. + The second parameter represents the soft limit. The third parameter represents the hard limit. This may be specified multiply times, but only once for each type. @@ -128,7 +128,7 @@ Rule Documentation: - The second Content represents when to run this re-run is triggered, which is either "success" (return code of 0) or "failure" (return code is not 0). - - The third Content and more represent additional options for fine tuning how the re-run is perforrmed\: + - The third Content and more represent additional options for fine tuning how the re-run is Performed\: When "delay", followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run. When "max", followed by a positive number or the number 0 designating the maximum number of re-runs to perform. When "reset", the "max" re-run counter is reset for the opposite re-run when this re-run is triggered, such as\: diff --git a/level_3/controller/documents/time.txt b/level_3/controller/documents/time.txt index 14ad45e..b460fca 100644 --- a/level_3/controller/documents/time.txt +++ b/level_3/controller/documents/time.txt @@ -27,9 +27,10 @@ Time Documentation: For example, "2020:86400000000000" would represent: January 02, 2020 0:00 UTC. For example, "2020:86.4 TT" would represent: January 02, 2020 0:00 UTC. - A second unit of Time, called EpochTime, works the same way as Time except it represents seconds since Epoch where Epoch is defined as the povided year (unlike UNIX Epoch). - This unit is desigated "E". + A second unit of Time, called EpochTime, works the same way as Time except it represents seconds. + This unit is designated "E". The format is similar to Time, except there are two colons: "1970::1620874738" would represent: May 13, 2021 2:58:58 UTC. + When the year is not specified, then this is identical to UNIX Epoch. A unit of EpochTime by default is assumed to be in UTC. 1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime). -- 1.8.3.1