|author||Thomas Touhey <email@example.com>||2021-06-08 14:48:14 +0200|
|committer||Thomas Touhey <firstname.lastname@example.org>||2021-06-08 14:48:14 +0200|
Trying to describe processes and stuff. Not easy!
|-rw-r--r--||docs/system/process/concepts.rst (renamed from docs/system/process/contexts.rst)||8|
|-rw-r--r--||docs/system/process/manager-impl.rst (renamed from docs/system/process/manager-api.rst)||22|
|-rw-r--r--||docs/system/process/runtimes/native.rst (renamed from docs/system/process/process-api.rst)||16|
7 files changed, 122 insertions, 53 deletions
diff --git a/docs/explain/modem-protocols.rst b/docs/explain/modem-protocols.rst
index fcb5670..3cf000a 100644
@@ -337,12 +337,12 @@ Some known port protocols are the following:
* - 65533
- * - 65535
- - ``rednet-broadcast``
- - :ref:`rednet`
* - 65534
+ * - 65535
+ - ``rednet-broadcast``
+ - :ref:`rednet`
diff --git a/docs/system/process.rst b/docs/system/process.rst
index 5538e94..5f7e501 100644
@@ -1,11 +1,31 @@
thox processes and interactions
-thox provides `pre-emptive multitasking`_, which means that the tasks, wrapped
-in **processes** which corresponds to the system view of the tasks, are
-executed one after the other, and the system switches from one task to the
-other from time to time, without requiring the process to give control back
-to the system.
+ Introduce the concept of runtimes, i.e. Lua files e.g. in ``/lib/runtimes``
+ that run before the program main code to initialize the environment to
+ a standardized environment using the thox native process API.
+ Runtimes could include:
+ * Native thox process runtime (nothing).
+ * Extended compatibility (use the Lua current functions to give access
+ to obsolete or future utilities, not just those of the current Lua
+ * CraftOS runtime, which hides RPC calls between functions and constants
+ described by the CC:T reference.
+ * Other OS runtimes, such as OPUS runtimes.
+ The goal is to ease program compatibility while retaining the security
+ offered by the process design, as runtimes are constructs above the
+ native process API. Kind of like "subsystems" in Windows NT.
+ Such an option (e.g. ``runtime_path``) should be implemented in the
+ :lua:func:`os.run`, :lua:func:`os.run_file` and :lua:func:`os.run_code`
+thox provides multitasking_, which means that processor time is shared
+between multiple tasks, grouped in processes, automatically.
@@ -13,23 +33,38 @@ to the system.
monotasking system which implements `Terminate and stay
-You can find more information about processes and how they are managed
-in the following sections:
+When possible, thox multitasking will be `pre-emptive`_, which means that
+switching between processes can be done without requiring the process to
+give control back to the system; however, in some circumstances, this cannot
+be accomplished, therefore thox resorts to simple cooperative_ multitasking,
+which requires process to give control back to the system through any
+system call. For more details, see :ref:`explain-system-mt-using-lua`.
- :maxdepth: 2
+In the following sections, we will discuss the following points:
+ * The concepts used in this project: processes, contexts and interactions.
+ * The native thox runtime API.
+ * RPC APIs of native contexts, managed by the thox process manager.
+Then, if you want to go more in depth about the thox process manager, you can
+find information in the following sections:
-And find the APIs of the processes and process manager in the following
+ * How running and switching between processes is implemented.
+ * The manager implementation reference, i.e. how the manager is implemented
+ in terms of functions and objects.
+See all of these discussions and references in the following sections:
.. _Terminate and stay resident programs: https://en.wikipedia.org/wiki/Terminate_and_stay_resident_program
-.. _pre-emptive multitasking: https://wiki.osdev.org/Multitasking_Systems#Preemptive_Multitasking
+.. _multitasking: https://wiki.osdev.org/Multitasking_Systems
+.. _pre-emptive: https://wiki.osdev.org/Multitasking_Systems#Preemptive_Multitasking
+.. _cooperative: https://wiki.osdev.org/Multitasking_Systems#Cooperative_Multitasking
diff --git a/docs/system/process/contexts.rst b/docs/system/process/concepts.rst
index c57eff3..801bdae 100644
@@ -1,5 +1,9 @@
-thox contexts and interactions
+thox concepts: contexts and interactions
+ Talk about processes themselves.
Inter-process communication (IPC) serves, from a process's point of view, for
communicating with the hardware and other processes, allowing them to
diff --git a/docs/system/process/manager-api.rst b/docs/system/process/manager-impl.rst
index 8475da9..a396710 100644
@@ -202,28 +202,6 @@ Process Manager
Run the processes until there are none left.
-The process manager provides the initial process these RPC calls on its
-.. lua:module:: os.rpc
-.. lua:function:: alarm(seconds)
- Ask for an alarm to be sent to you in a given number of seconds.
- This function is usually called for sleeping a certain time,
- by calling it then waiting for the answer.
- Example usage:
- .. code-block:: lua
- -- Sleep for five seconds and a half.
:param seconds: Amount of seconds, possibly decimal.
:type seconds: number
:return: The actual number of seconds passed since the call.
diff --git a/docs/system/process/manager.rst b/docs/system/process/manager.rst
index ad69d98..ee71ba2 100644
@@ -3,7 +3,17 @@
thox process manager
-This is accomplished using two tools we have at our disposal in Lua:
+The thox process manager, provided through the ``thox`` package, provides
+the main process manager which implements the concept of processes and
+switches between them.
+How this is accomplished in Lua
+Lua facilities we use in order to implement the thox process manager are
@@ -12,12 +22,13 @@ Coroutines are basically functions that can start and stop as needed. You
give them thread control by “resuming” them, and they give you control back
when they have a value for you, which is called “yielding”, when an error
occurred and they didn't catch it, or when the function terminated its
-execution. They do not run concurrently; in another language you might be
-familiar with, Python, has called them `generators`_.
+execution. They do not run concurrently; they resemble what Python calls
+`generators`_, although Python has `coroutines of its own
-This, however, only sets ground for a `cooperative multitasking`_ system.
-In order to make it pre-emptive, we need to force the processes to yield
-after a certain time, e.g.:
+Coroutines, however, only sets ground for a `cooperative multitasking`_
+system. In order to make it pre-emptive, we need to force the processes to
+yield after a certain time, e.g.:
.. code-block:: lua
@@ -41,6 +52,11 @@ Which gives the following result:
As you can see, the hook is only called for the coroutine it was set into.
+ Finish describing this, and express in this section how debug utilities
+ aren't always present in the environments we support...
System calls and coroutines
@@ -188,6 +204,7 @@ Step 1 runs as follows:
.. _pre-emptive multitasking: https://wiki.osdev.org/Multitasking_Systems#Preemptive_Multitasking
.. _cooperative multitasking: https://wiki.osdev.org/Multitasking_Systems#Cooperative_Multitasking
+.. _Python coroutines: https://docs.python.org/3/library/asyncio-task.html
.. _Coroutines: http://www.lua.org/manual/5.3/manual.html#2.6
.. _debug.sethook(): http://www.lua.org/manual/5.3/manual.html#pdf-debug.sethook
.. _context switching: https://wiki.osdev.org/Context_Switching
diff --git a/docs/system/process/native-contexts-apis.rst b/docs/system/process/native-contexts-apis.rst
new file mode 100644
@@ -0,0 +1,27 @@
+APIs of contexts managed by the process manager
+The process manager manages a few contexts of its own.
+ Continue to write this.
+The process manager provides the initial process these RPC calls on its
+.. lua:module:: os.rpc
+.. lua:function:: alarm(seconds)
+ Ask for an alarm to be sent to you in a given number of seconds.
+ This function is usually called for sleeping a certain time,
+ by calling it then waiting for the answer.
+ Example usage:
+ .. code-block:: lua
+ -- Sleep for five seconds and a half.
diff --git a/docs/system/process/process-api.rst b/docs/system/process/runtimes/native.rst
index 2a9cdfc..b589726 100644
@@ -1,8 +1,16 @@
-thox process API
+thox native process runtime API
-When started, every process has access to the utilities described in
-`the Lua 5.3 manual`_.
+When started, a thox process has access to a given set of functions and
+constants; this document describes them.
+ When started, every process should have access to the native functions
+ to the current Lua function, e.g. those described in
+ `the Lua 5.3 manual`_.
+ Maybe make a table and check which utilities are available or not.
.. lua:module:: os