aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas Touhey <thomas@touhey.fr>2021-06-08 14:48:14 +0200
committerThomas Touhey <thomas@touhey.fr>2021-06-08 14:48:14 +0200
commit3497ea7ab2e19178f465fb6237d91679fb8cd70d (patch)
treef120a8b66d8661bbcecedc0149b2d8a5979364ad
parent3ad6b58a4ee66fb319f45e55c6152de7deefadce (diff)
Trying to describe processes and stuff. Not easy!
-rw-r--r--docs/explain/modem-protocols.rst6
-rw-r--r--docs/system/process.rst67
-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/manager.rst29
-rw-r--r--docs/system/process/native-contexts-apis.rst27
-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
--- a/docs/explain/modem-protocols.rst
+++ b/docs/explain/modem-protocols.rst
@@ -337,12 +337,12 @@ Some known port protocols are the following:
* - 65533
- ``rednet-repeat``
- :ref:`rednet`
- * - 65535
- - ``rednet-broadcast``
- - :ref:`rednet`
* - 65534
- ``gps``
- :ref:`modem-gps`
+ * - 65535
+ - ``rednet-broadcast``
+ - :ref:`rednet`
.. todo::
diff --git a/docs/system/process.rst b/docs/system/process.rst
index 5538e94..5f7e501 100644
--- a/docs/system/process.rst
+++ b/docs/system/process.rst
@@ -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.
+.. todo::
+
+ 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
+ function).
+ * 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`
+ functions.
+
+thox provides multitasking_, which means that processor time is shared
+between multiple tasks, grouped in processes, automatically.
.. note::
@@ -13,23 +33,38 @@ to the system.
monotasking system which implements `Terminate and stay
resident programs`_.
-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`.
-.. toctree::
- :maxdepth: 2
+In the following sections, we will discuss the following points:
- process/contexts
- process/manager
+ * 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
-sections:
+ * 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:
.. toctree::
:maxdepth: 2
- process/process-api
- process/manager-api
+ process/concepts
+ process/runtimes/native
+ process/native-contexts-apis
+ process/manager
+ process/manager-impl
.. _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
--- a/docs/system/process/contexts.rst
+++ b/docs/system/process/concepts.rst
@@ -1,5 +1,9 @@
-thox contexts and interactions
-==============================
+thox concepts: contexts and interactions
+========================================
+
+.. todo::
+
+ 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
--- a/docs/system/process/manager-api.rst
+++ b/docs/system/process/manager-impl.rst
@@ -202,28 +202,6 @@ Process Manager
Run the processes until there are none left.
-RPC bindings
-------------
-
-The process manager provides the initial process these RPC calls on its
-default context:
-
-.. lua:module:: os.rpc
- :noindex:
-
-.. 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.
- rpc.alarm(5.5)
-
: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
--- a/docs/system/process/manager.rst
+++ b/docs/system/process/manager.rst
@@ -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.
+
+.. _explain-system-mt-using-lua:
+
+How this is accomplished in Lua
+-------------------------------
+
+Lua facilities we use in order to implement the thox process manager are
+the following:
* `Coroutines`_;
* `debug.sethook()`_.
@@ -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
+<Python coroutines_>`_.
-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.
+.. todo::
+
+ 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
index 0000000..21559f6
--- /dev/null
+++ b/docs/system/process/native-contexts-apis.rst
@@ -0,0 +1,27 @@
+APIs of contexts managed by the process manager
+===============================================
+
+The process manager manages a few contexts of its own.
+
+.. todo::
+
+ Continue to write this.
+
+The process manager provides the initial process these RPC calls on its
+default context:
+
+.. lua:module:: os.rpc
+ :noindex:
+
+.. 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.
+ rpc.alarm(5.5)
diff --git a/docs/system/process/process-api.rst b/docs/system/process/runtimes/native.rst
index 2a9cdfc..b589726 100644
--- a/docs/system/process/process-api.rst
+++ b/docs/system/process/runtimes/native.rst
@@ -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.
+
+.. todo::
+
+ 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