提交: de487fa932d9abaa2ab6a68c11d6c66483d57d03 - DocIdeas (hg)

Commit MetaInfo

• 修訂: de487fa932d9abaa2ab6a68c11d6c66483d57d03 (tree)
• 時間: 2022-10-02 21:51:50
• 作者: Albert Mietus < albert AT mietus DOT nl >
• Commiter: Albert Mietus < albert AT mietus DOT nl >

Log Message

~Finished 8.ConcurrentComputingConcepts (CCC)

Change Summary

• modified: CCastle/1.Usage/1.CompilerCompiler.rst
• modified: CCastle/1.Usage/4.FSMs-are-needed.rst
• modified: CCastle/1.Usage/zz.todo.rst
• modified: CCastle/index.rst
• modified: Makefile
• modified: _external_templates/static/SwBMnl+rtfd.css
• add: CCastle/1.Usage/7.BusyCores.rst
• add: CCastle/1.Usage/BusyCores-sidebar-CPython_threads.irst
• add: CCastle/2.Analyse/2.grammar_code.rst
• add: CCastle/2.Analyse/3.NoActions.rst
• add: CCastle/2.Analyse/5.FSM-syntax.rst
• add: CCastle/2.Analyse/5b.short_FSM-vs-Grammar.rst
• add: CCastle/2.Analyse/8.ConcurrentComputingConcepts.rst
• add: CCastle/2.Analyse/CCC-sidebar-CS.irst
• add: CCastle/2.Analyse/CCC-sidebar-MA-links.irst
• add: CCastle/2.Analyse/CCC-sidebar-calc-demo.irst
• add: CCastle/2.Analyse/CCC-sidebar-concurrency.irst
• add: CCastle/2.Analyse/FSM-sidebar-SCXML.irst
• add: CCastle/2.Analyse/FSM-sidebar-SMC.irst
• add: CCastle/2.Analyse/FSM-sidebar-plantUML.irst
• add: CCastle/2.Analyse/Wikipedia-PetriNet.gif
• add: CCastle/2.Analyse/index.rst
• add: CCastle/3.Design/6.FSM_try_1.rst
• add: CCastle/3.Design/index.rst
• add: CCastle/3.Design/zz.todo.rst
• add: std/localtoc2.irst
• delete: CCastle/2.Design/eval/5.0.eval-syntax.rst
• delete: CCastle/2.Design/eval/5.1.FSM_try_1.rst
• delete: CCastle/2.Design/eval/index.rst
• delete: CCastle/2.Design/eval/sidebar-SCXML.irst
• delete: CCastle/2.Design/eval/sidebar-SMC.irst
• delete: CCastle/2.Design/eval/sidebar-plantUML.irst
• delete: CCastle/2.Design/index.rst
• delete: CCastle/2.Design/syntax/2.grammar_code.rst
• delete: CCastle/2.Design/syntax/3.NoActions.rst
• delete: CCastle/2.Design/syntax/index.rst
• delete: CCastle/2.Design/zz.todo.rst

差異

diff -r 79905a473ddb -r de487fa932d9 CCastle/1.Usage/1.CompilerCompiler.rst
--- a/CCastle/1.Usage/1.CompilerCompiler.rst	Fri Jun 10 19:18:51 2022 +0200
+++ b/CCastle/1.Usage/1.CompilerCompiler.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -131,13 +131,16 @@
 ready to use; not more manual scanning and parsing. And when the file-structure is slightly updated, you just add a few
 details to the grammer.
 
-Castle, has it build-in
-=======================
+Castle has it build-in
+======================
+
+Grammars makes reading text easy. Define the structure, call the “main rule” and use the values. Castle makes that
+simple!
 
 .. use:: Castle has build-in grammers support
    :ID: U_Grammers
 
-   In Castle one can define a grammer, directly into the source-code; the syntax supports that. As shown above.
+   In Castle one can define a grammer directly into the source-code; as :ref:`grammmar-code`!
 
    And, like many other details, the language is hiding the nasty details of parsing-strategies. There is no need to
    generating, compiling, and use that code, with external tools. All that clutter is gone.
@@ -152,11 +155,10 @@
 
 To use the grammar you simply call one of those rules as a function: pass the input (string) and it will return a
 (generic) tree-structure.
+When you simple like to verify the syntax is correct: use the tree as a boolean: when it not-empty the input is valid.
 |BR|
-When you simple like to verify the syntax is correct: use the tree as a boolean: when it not-empty the input is valid.
+Typically however, you traverse that tree, like you do in many situations.
 
-But typically you proces/use that tree: like you do in many situations. Read the configuration values, walk over the
-tree, of traverse it as-if it is a DOM. You can even use Castle’s :ref:`matching-statements` to simply that.
-
-Grammars makes reading text easy. Define the structure, call the “main rule” and use the values. Castle makes that simple!
-
+To read that early configuration: parse the file and walk over the tree.  Or use it “ala a DOM” by using Castle’s
+:ref:`matching-statements` to simply. Curious on how that works: continue reading in :ref:`grammmar-code`.
+Or skip to  “Why there are :ref:`G2C-actions`”.

diff -r 79905a473ddb -r de487fa932d9 CCastle/1.Usage/4.FSMs-are-needed.rst
--- a/CCastle/1.Usage/4.FSMs-are-needed.rst	Fri Jun 10 19:18:51 2022 +0200
+++ b/CCastle/1.Usage/4.FSMs-are-needed.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -178,12 +178,12 @@
 event *TurnOff* will turn-off the system -- but you only need to add one rule!
 
 
-Concurent states (Orthogonal regions)
---------------------------------------
-Concurent states are more complex as super/subs-states. It are kind of local states are active
+Concurrent states (Orthogonal regions)
+---------------------------------------
+Concurrent states are more complex as super/subs-states. It are kind of local states are active
 *simultaneously*. `Wikipedia <https://en.wikipedia.org/wiki/UML_state_machine#Orthogonal_regions>`__ has a nice example
 with the num-lock and caps-lock key: both change ``state`` -- one to select capital on/of, and one to prefer arrow over
-number -- but those ``states`` are *independent* and **concurent**.
+number -- but those ``states`` are *independent* and **concurrent**.
 
 Again, the advantage is it makes the “FSM table” shorter and better to maintain.
 
@@ -242,7 +242,7 @@
    #. Epsilon transitions
    #. *‘Instantly’* transitions (see above: a special kind of :math:`\epsilon`\-transition)
    #. Hierarchically superstates (or sub-states)
-   #. Concurent states (Orthogonal regions)
+   #. Concurrent states (Orthogonal regions)
    #. Moore_ and Mealy_ transitions
    #. Entry and Leave transitions
 

diff -r 79905a473ddb -r de487fa932d9 CCastle/1.Usage/7.BusyCores.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/1.Usage/7.BusyCores.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,311 @@
+.. include:: /std/localtoc.irst
+
+.. _BusyCores:
+
+======================
+Keep those cores busy!
+======================
+
+.. post::  2022/07/06
+   :category: Castle, Usage
+   :tags: Castle, Concurrency
+
+   I always claim that most computers will have 1024 or more cores before my retirement. And that most embedded systems
+   will have even more, a decade later. However, it’s not easy to write technical software for those “massive-parallel
+   embedded computers”, not with the current languages -- simple because a developer has to put in too many details.
+   Accordingly, the “best, ever” programming language should facilitate and support “natural concurrency”.
+
+   In Castle, you can easily write code that can run efficiently on thousands of cores.
+
+Why do we get more and more cores?
+==================================
+
+Moore `observed already in 1965 <https://en.wikipedia.org/wiki/Moore's_law>`_ that the number of transistors on a chip
+doubles every 2 years. That made memory cheaper and computers faster. For years we have seen that: CPUs have grown from
+4-bit to 8, 16, 32, and now 64-bit; and the ‘clock-frequently’ has risen into the giga-hertz. This comes (almost) for
+free when the *‘gate-size’ dropped* -- roughly, a ‘gate’ is the smallest “pixel” when a chip is manufactured. By
+shrinking the gates one can put more transistors on a chip and at the same time those chips become faster and use less
+power --this comes automatically; as you may remember from your (advanced) physics lessons.
+
+But there are limits: transistors can’t switch much faster than a few billion times a second. When we crossed that
+border, just making gates smaller didn't increase the CPU’s speed. But there are other tricks; like huge caches very
+close to (or ‘in’) the CPU. Again it made computers faster, without much work for the SW developer.
+Another limit is the number of transistors you can utilize in a CPU (or the cache). One can double the number of
+transistors almost without limit, but does it again double your CPU-speed? *No*, not anymore, that threshold is passed a
+few years back.
+
+A new trick was needed: put more CPUs onto *one* chip. Essentially that is what Multi-Core_ does: every core is
+fundamentally an independent CPU - but as we used that word already, we use ‘core’ for those copies. The amount of work
+a chip can do with two cores doubles — at least potentially. Using Moore’s low, the number of cores will double be every
+18-24 months; or 30 times more in a decade. Currently, many (mobile phone) SoCs already have more than 10 cores — when
+counting both GPUs & CPUs. That is 300 in 10 years, and 9-thousand in 20 years!
+
+Programming many cores
+======================
+
+Although the promise of Multi-Core_ is an unlimited expansion of speed, it requires us to adapt our programming
+abilities. Transitional “sequential” programs take for granted that the CPU can do only one thing at a time; at many
+levels. With Multi-Core_ this fundamentally changed. There is no speed up when we don’t use all cores. This is not much
+of an issue for a low number of cores; there are plenty of other/background tasks. Even ‘single threaded’ code will
+run faster when “your core” isn’t interrupted; when those auxiliary processes can run in parallel on another core.
+
+When the number of cores rises this does not scale; more and more cores become idle. Now, your code has to use both
+concurrency_ and parallelism_. But also handle Critical-Sections_, Semaphores_ (and friends) to  synchronise  tasks.
+
+
+.. include:: BusyCores-sidebar-CPython_threads.irst
+
+Threading
+---------
+
+Threads_ have become popular to accomplish parallelism_ but have drawbacks too. They originated (long, long back) in
+“real-time & embedded” programming; -- those systems didn't have an OS nor processes and used a concept that resembles
+threads.  Other computers (mostly Unix/Posix) used “processes” to run many tasks --Windows/Dos wasn't relevant; it was
+(mostly) single-user. Mid 199x threads_ become available as “real-time extensions”; initially within a single process —
+and so running on a single core. Al this was long before Multi-Core_ hardware was accessible, and studies started on how
+to combine threads & processes — should the kernel handle that or not, and how to avoid overhead. This all changed with
+Multi-Core_; need threads_ that can run in parallel on multiple cores.
+
+Still, it is not trivial to programming with (raw) threads.
+
+Bugs
+~~~~
+A lot of new bugs popped up when developers started to use threads_. One had to learn about concurrency_, parallelism_,
+and their difference. And that two threads can be intertwined in not foreseen ways; multiple threads_ can access
+the same variable. A single line became suddenly not atomic anymore -- even a single assignment is not.
+|BR|
+We mastered that today, at least mostly. There are still many quizzes about that, and many do not pass the tricky
+ones. More bothersome is that no one knows how to compose tests to verify the absents of this kind of Heisenbugs_
+
+Overhead
+~~~~~~~~
+Threads_ have more handicaps: it is hard to gain the speed up aiming for. Partly because threads_ themself have a lot of
+overhead (especially to start/stop them). But it is also hard to “get” the right number of threads_. Many opinions on
+this exist -- like one thread per core [#wrong]_ -- but hardly (or non) theory on this.
+
+A bigger factor is indirect overhead; especially in CPU-bound (see below) systems. Then, the outcome of a calculation in
+one thread is routinely needed for an algorithm in another thread -- if not, why use threads? That involves sharing data [#share]_
+
+Scaling
+~~~~~~~
+When we get more and more cores, we need more and more concurrent task to get the speed up we like. With (raw) threads_
+this becomes more and more an issue. More threads_ may imply more bugs; notably hard to find Heisenbugs_. More threads_
+make is harder to limit the overhead.
+
+To summaries: Threads_ do no scale well; there is a limit to the number of threads we can manage as a
+software-developers. So, a new “trick” is needed.
+
+
+IO vs CPU Bound
+---------------
+
+Another --often overlooked, but important-- aspect is ‘how & why’ threads are used. Many applications interact with a
+user and/or have lots of other IO. Input & output is slow compared with (the GigaHertz of) the CPU itself. The result is that
+“the computer” has to wait on the user, on the network or disk [#SDD]_; this is called *IO-bound*
+|BR|
+With threads_, it’s easy to speed up IO-bound systems. Then (only) a single thread is waiting; all other threads can
+continue. This works even on a single-core. This IO-bound aspect was (one of) the primary ambitions when introducing
+“real-time” threads. With Multi-Core_ this scales quite well; peculiarly when most threads do about the same. As in a
+web server for instance.
+
+Technical, embedded applications generally differ. They are mostly *CPU-bound*; as there is nothing to be waiting on. In
+the extreme case, the processor is constantly busy, say doing calculations.
+|BR|
+Then, just adding threads will not lead to speed up; as the processor is busy anyhow; more processor power is
+needed! Along with a gentle distribution of the work gently over the available cores. Ideally, all cores should do an
+even part of that calculation.
+
+Using threads_ with CPU-bound systems is much harder. It is complicated to split the work, it’s backbreaking to allot
+the tasks over the cores equally, and troublesome to minimize the overhead. But easy to introduce flaw ...
+|BR|
+The center of attraction in this blog(s) is those knotty, “mostly CPU-bound”, technical, modern-embedded systems, as
+you already expected.
+
+
+Alternatives
+============
+
+Raw threads_, as in pthreads_, are not the only option; there are contemporary alternatives. For the most part,
+they use threads to implement a more abstract interface; to unburden developers for those technicalities.
+
+We introduce a few but leave the details to the next blog: the study on :ref:`ConcurrentComputingConcepts`.
+
+Thread-Pools
+------------
+
+Starting & stopping a thread is relatively costly; this makes them less suited for short-running tasks --then the relative
+overhard is big. The Thread-Pool_ design pattern tackles this by creating (long-running) “worker threads” and a “task
+queue(s)”. Running many (small) tasks in the same thread reduces the overhead. Also, the task will start (and end)
+a bit earlier; as threads are pre-created
+
+.. tip::
+
+   I have given a “Design Workshop” on the `“ThreadPoolExecutor”
+   <http://mess.softwarebetermaken.nl/en/latest/SoftwareCompetence/DesignWorkShops/TPE/>`_, in another series,
+   Have a look when you like to learn more about this pattern.
+
+Some languages support this concept naturally; in others, it is more like an add-on option on threads. Besides
+depending on the language implementation (compiler and runtime libraries), it may or *may not* have the speeding-up
+benefit when using many cores.  For example, the python “ThreadPoolExecutor” is a likable, sound example; but as
+(C)Python can’t run multiple threads simultaneously, you will not gain a speed up on CPU-bound systems. Still, we can
+use it as inspiration.
+
+The Thread-Pool_ pattern gives us a simple alternative to (raw) threads; especially when the thread-part is buried and
+not visible to the developer. Then the programmer can focus on defining small (concurrent) tasks and the “computer”
+can add details such as how many threads, on which core(s), and manage them.
+
+GCD (LibDispatch)
+-----------------
+
+Grand Central Dispatch, or GCD_, is a technology invented by Apple add developed as open-source, that takes the idea of
+Thread-Pools a step further. Therefore they added an extension to the C-language too: “blocks_” -- A kind of anonymously (unnamed),
+inline, nested functions, that act as a closure. It sounds a bit complicated, but most developers find it easy to use
+[#bold-on]_.
+
+A “block” is like a function, that can be dispatched (scheduled) for independent execution. Typical a block is
+small --so we have lots of capability for simultaneous execution-- without introducing much overhead [#one-percent]_.
+
+.. seealso::
+
+   * The GCD “scheduler” is available as `libdispatch <https://github.com/apple/swift-corelibs-libdispatch>`_.
+   * The blocks_ extension is available for LLVM. Apparently, GCC is not supporting it (anymore).
+
+GCD_ also supports Objective-C, C++, and Swift. Then, the language semantics differ a bit (making it
+easier to use); but the concept is the same: Store the “environment” (see: closure_) of the lexical scope of the nested
+function-block in a task-object, and put them on (FIFO) queue. And have some long-running (raw, invisible) threads
+processing those task-objects. As those tasks are isolated, running them is easy.
+|BR|
+The developer is hidden from the threads -- (s)he is not even aware of them! Or actually, there is just this general
+understanding the “raw threads” are used in the background, but that is not required. Any “scheduler” will do!
+
+
+.. _BC-events:
+
+Events (interrupts)
+-------------------
+
+Events are a completely contrasting approach, avoiding threads at all. They are also known as *interrupts* for low-level
+close-to-hardware developers. Events are primarily introduced for “Windowing programming [#Windowing]_. Up to then, a
+program stared at ``main()``, jumping to subroutines in the order the programmers has written them. For GUIs (or
+Windowing-application, as we called them), that was inconvenient -- the user should be in control. When “pressing a
+button (or “Widget”) the system generated an “event”.
+|BR|
+The developers had to write “event-handlers” --functions, but with a predefined signature-- and register each, passing
+the kind of event(s) they should active them. This was new, completely different (and strange, back then). A function got
+names as ``OnButton_XXX_Press(event)``, and where called “automagically”.
+
+You can imagen the implementation now: a queue and an event-loop. But this concept shows something else too, as a
+side-effect: (virtual) concurrent programming.
+
+Event- (handlers) are small “task alike” independent routines, that become active when needed: when some input-data becomes
+available. All those “tasks” are atomic (short living) and where the controll-flow is not specified. It appears as if
+all those small, little task can run concurrent -- as the user can quickly trigger many event “at once”. In modern
+systems the results of the events emerge even “asynchronous” -- then we often call it “reactive”.
+|BR|
+This really happens for “hardware interrupts”. Those interrupts truly are asynchronous of the “main code”. And one has
+to handle them immediacy (or the input is gone, and a result will be wrong!). An “interrupt-handler” is very alike an
+event-loop-handler; albeit at another scale.
+
+Both variants shows in there function-names how many developers would like to deal with asynchronous, concurrent “tasks”:
+:samp:`On {EventType} Run {{Code}}`.
+
+
+Castle activates all cores
+==========================
+
+An “*ideal language*” should make it easy to distribute the load over many processors. That should come
+automatically; without the developer has to put a load of effort in. That is also one of the aspect :ref:`CC` is
+enabling --and as Castle supports :ref:`CC` (and is the best language, ever -- so quite close to “ideal”)-- the language
+should be designed to enable this.
+
+.. use:: In Castle is easy to use thousands of cores
+   :ID: U_ManyCore
+
+   A “CC Castle” program can run on many cores, without the developer needs to describe “manually” how to do that.
+
+   At the same time it should run efficiently. The goals is **not** to keep all cores *busy*, but to use (all) cores to
+   gain maximal speed up.
+
+Distributing tasks over multiple cores (or even distributed computers) [#web]_ is not new. In
+:ref:`ConcurrentComputingConcepts` we describe some (common, theoretical) concepts, especially the
+:ref:`CCC-Actors`. What we like to use for CCastle.
+
+----------
+
+.. rubric:: Footnotes
+
+.. [#python27-outdated]
+   Both the Jython and Iron-Python implementations are effectively dead as there is only support for Python-2.7. That
+   however is ortogonal on the (alternative) way it handles threads.
+
+.. [#GIL-speed]
+   Using the GIL was not a bad option. It made code fast, both for non-threading as for threading!
+   |BR|
+   Many attempt have made to “remove the GIL”: all failed. Not because removing the GIL (itself) is hard, but as the
+   replacements made the code slower. Always for single-threaded applications; but sometimes the extra overhead was even
+   bigger then the speed up when using all cores. And even that was mainly in the “first tackle”, let it be a lesson
+   for “Busy Cores”:
+
+   *It not about using all cores, it about the speed up!*
+
+.. [#CS-link]
+   See :ref:`ConcurrentComputingConcepts` for more on Critical-Sections_ and other well-know concepts and how they relate.
+
+
+.. [#web]
+   A trivial example of dividing work over multiple computers (and so cores) is the “Web”. You have at least two
+   concurrent (active) components: the server and the brouwer. Usually there a more. By example, the server-side run’s
+   the application- a web-, and database-server. And “the web itself” has many active components, like routers, ect. And
+   all are programmed in a style that the developer doesn't need to know all those details(!).
+
+.. [#wrong]
+   Having a 1:1 relation is very populair point of view, at some places. But most probably wrong -- although that is an
+   assumption too. In addition, it does not scale (what when the number of core double?), and hard to manage.
+   |BR|
+   Also see: the section about IO- vs CPU bound.
+
+.. [#share]
+   Sharing can be done by a shared-data or by sending messages. For the developer the latter has the advantage that no
+   (synchronised) shared, variables are needed. But that us just an abstraction; at a lower level there is some memory
+   that is written by one an read by another thread -- and so need synchronisation and exclusiveness.
+
+.. [#SDD]
+   Even the fasterst “SSD-disks” are slow. Although they are a hundred times faster them *platters*, with accesstimes in
+   the *micro-seconds range*. That is a thousand times slower as the *nano-seconds* a processors is working in.
+
+.. [#bold-on]
+   This “C-blocks” concept however is common in other language; its very common java-script code. For C feels a bit as
+   “bolded-on” on the existing language -- and it is. When using it in Objective-C (and C++), it is still “bold-on”, but
+   more natural due the OO-aspect. And in Swift, which is designed with this concept from day 1, is just a part of the
+   language.
+   |BR|
+   Something similar will apply to Castle too: by design a language with fine-grained concurrency, we can learn from
+   existing concepts, combine them and make it trivial to use.
+
+.. [#one-percent]
+   By hearsay, GCD_ introduces a about a dozen instruction per dispatched “block”. So, when the blocks are about a
+   thousand instructions, that results in about 1%; which is acceptable.
+   Still, when googling, you will find people that try to dispatch a hand-full on instructions (like a single
+   statement); it works (as the result is correct), but doesn't (as it is slowish). Although, when you would do that
+   with raw-threads (create/stop a pthreads pro statement) you will really notice the slow-down!
+
+.. [#Windowing]
+   Both `X-Window <https://en.wikipedia.org/wiki/X_Window_System>`_ (or “X11”) and `MS-Windows
+   <https://en.wikipedia.org/wiki/Windows_1.0x>`_ heavily depend on this (then new, 1984 resp 1985) concept of an
+   “event-loop”. 
+   
+   application be
+
+.. _Multi-Core:			https://en.wikipedia.org/wiki/Multi-core_processor
+.. _Concurrency:		https://en.wikipedia.org/wiki/Concurrency_(computer_science)
+.. _parallelism:		https://en.wikipedia.org/wiki/Parallel_computing
+.. _Critical-Sections:		https://en.wikipedia.org/wiki/Critical_section
+.. _Semaphores:			https://en.wikipedia.org/wiki/Semaphore_(programming)
+.. _Threads:			https://en.wikipedia.org/wiki/Thread_(computing)
+.. _Heisenbugs:			https://en.wikipedia.org/wiki/Heisenbug
+.. _pthreads: 			https://en.wikipedia.org/wiki/Pthreads
+.. _Thread-Pool:		https://en.wikipedia.org/wiki/Thread_pool
+.. _GCD:			https://en.wikipedia.org/wiki/Grand_Central_Dispatch
+.. _blocks:			https://en.wikipedia.org/wiki/Blocks_(C_language_extension)
+.. _closure:			https://en.wikipedia.org/wiki/Closure_(computer_programming)
+.. _

diff -r 79905a473ddb -r de487fa932d9 CCastle/1.Usage/BusyCores-sidebar-CPython_threads.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/1.Usage/BusyCores-sidebar-CPython_threads.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,35 @@
+.. -*- rst -*-
+   included in  `4.FSMs-are-needed.rst`
+
+.. _Threads-in-CPython:
+.. sidebar:: Threads in CPython
+
+   Python_ was conceived in early 198X when the word was single-core. And even though there were already debates on very
+   advanced `M:N <https://en.wikipedia.org/wiki/Thread_(computing)#M:N_(hybrid_threading)>`__ models, threads_ were
+   singular. When one thread is running, “all cores” are busy...
+   |BR|
+   Back then, CPython_ made the design choice to use the now-famous GIL_ [#GIL-speed]_ to implement Critical-Sections_
+   [#CS-link]_.
+
+   In hindsight, that was maybe not the best approach. Although the Python developer can use sound threads, and
+   CPython_ implements them using a pthreads_\-thread for every python-thread, this GIL results in no speed-up on a
+   Multi-Core_ system. As many studies show: all cores will be used(!) but only one at a time. At any moment, only one
+   core is active.
+   |BR|
+   A clear example, showing that *“keeping the cores busy”* is not trivial.
+
+   And remember: it’s not a flaw of Python_. Other implementations --like, Jython_ [#python27-outdated]_ using the
+   JAVA-VM runtime and IronPython_ [#python27-outdated]_ that uses the .Net environment-- use another (more modern)
+   design; in both cases, we get the Multi-Core_ speed-up that we expect.
+
+
+
+
+
+
+.. _CPython:		https://en.wikipedia.org/wiki/CPython
+.. _Python:		https://en.wikipedia.org/wiki/Python_(programming_language)#History
+.. _pthreads: 		https://en.wikipedia.org/wiki/Pthreads
+.. _GIL:		https://en.wikipedia.org/wiki/Global_interpreter_lock
+.. _Jython:		https://en.wikipedia.org/wiki/Jython
+.. _IronPython:		https://en.wikipedia.org/wiki/IronPython

diff -r 79905a473ddb -r de487fa932d9 CCastle/1.Usage/zz.todo.rst
--- a/CCastle/1.Usage/zz.todo.rst	Fri Jun 10 19:18:51 2022 +0200
+++ b/CCastle/1.Usage/zz.todo.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -17,7 +17,11 @@
 
    * Replace the “actions” in a grammar.
 
-     .. seealso:: :ref:`G2C-actions`
+     .. seealso::
+
+        * :ref:`G2C-actions`
+        * :ref:`CyclicWoods`
+
 
 .. _Declarative-programming:
 
@@ -35,3 +39,37 @@
    * Argparse (vs loop over argv) is a second example
 
    .. note:: CCastle: blog: “(1) declare what you need”. Declarative style programing. Eg loop over Argv vs argparse, makefiles
+
+
+.. _CyclicWoods:
+
+Cyclic woods (todo)
+===================
+
+.. todo:: Generalise and abstract the famous tree-structure and allow cycles 
+
+   E.g. a AST is tree with “cycles”: Each var is defined and used. Use “href” alike
+
+   .. seealso:: Its is (maybed) related to :ref:`matching-statements`
+
+.. _CC:
+
+Concurrent//Connected Components (ToDo)
+=======================================
+
+.. todo:: Write a few blog about the CC-concept
+
+.. _XXX:
+
+XXX (ToDo)
+==========
+
+.. _CC-example-Sieve:
+
+Sieving Prime components (ToDo)
+===============================
+
+.. _Castle-Tools:
+
+Castle Tools (ToDo)
+===================

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/2.grammar_code.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/2.grammar_code.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,235 @@
+.. include:: /std/localtoc.irst
+
+.. _grammmar-code:
+
+===============
+Grammar is code
+===============
+
+.. post:: 2022/05/14
+   :category: Castle, DesignStudy
+   :tags: Castle, Grammar, PEG
+
+   In :ref:`Castle-CompilerCompiler` we have seen that we can define a grammar within a Castle-program. And we have
+   argued that each grammars-rule can be considered as a function.
+
+   In this post, we look into de details of how this works. And will confirm grammars is code ...
+
+Let’s start with an example. The grammer below is a simplified description of how a (PEG) parsing-rule looks like. The
+syntax in Castle is a bit more complicated, by having more details and options; but very simular. Most of the
+Caste-grammers can be parsed by the grammer below!
+
+.. code-block:: PEG
+
+   PEG_rule        <-  rule_name '<-' expression ';' ;
+   expression      <-  ordered_choice+ ;
+   ordered_choice  <-  sequence ( '|' sequence)* ;
+   sequence        <-  group | atom ;
+   group           <-  '(' expression ')' ;
+   atom            <-  rule_xref | str_lit | regexp ;
+   str_lit         <-  '"'  /[^"]*  '"' ;
+   regexp          <-  '/'  /[^/]*  '/' ;
+   rule_name       <-  ID ;
+   rule_xref       <-  ID ;
+
+With this grammer we can read and check whether an a string is a valid rule by simply calling:
+:math:`ast:=PEG\_rule(single\_line)`. When not, ``ast`` is :math:`False`, else ``ast`` has 4 children (or fields).
+Where :data:`ast[0]` represent the ``rule_name``, :data:`ast[2]` is an ``expression``; which is a sequence of
+``ordered_choice``\(s).
+|BR|
+As the rule has two constants :data:`ast[1]` and :data:`ast[3]` will always match the strings *‘<-’* and *‘;’*.
+
+
+Grammar to code
+===============
+
+Before we study how Castle *expands* a grammar to code, let examine how to do that by manually crafted code, or using a
+external compiler-compiler. In both cases, we will focus on the “validation” part only. And we skip a lot of details;
+assuming you know a bit of theory of (PEG) parser. When not, read Guido van Rossum’s excellent blog-series `PEG Parsing
+Series Overview <https://medium.com/@gvanrossum_83706/peg-parsing-series-de5d41b2ed60>`__
+
+
+Hand written code
+-----------------
+
+Again, let’s suppost we like to verify a string contains a *peg-rule*. Then we need some functions [#func]_, which signature
+are something like:
+
+.. tabs::
+
+   .. code-tab:: python
+
+      def PEG_rule(text: str) -> ast : ...
+      def expression(text: str) -> ast : ...
+      def ordered_choice(text: str) -> ast : ...
+      def sequence(text: str) -> ast : ...
+      ...
+
+   .. code-tab:: c
+
+      ast PEG_rule(char* txt);
+      ast expression(char* txt);
+      ast ordered_choice(char* txt);
+      ast sequence(char* txt);
+      ...
+
+Where we assume the type ``ast`` is defined in the chosen language and will be Null/None/Empty to signal :math:`False`:
+not valid.
+
+The implementation of ``PEG_rule()`` checks thats the input-string starts with a ``rule_name``, followed by the literal
+string **“<-”**, then has an ``expression`` and finally the literal string **“;”**. When one of those (four) steps fail,
+we return :math:`False`.
+|BR|
+We follow this pattern for all rules.
+
+This concept is easy to implement: each rule-function calls other rule-functions as defined by the grammar. When we
+need to check for a literal string we use :func:`expect(txt: str, literal: str) -> bool`. Also, we need a function to find
+an ID; again easy. Sometimes we need to implement a loop --to handle ``*`` and ``+``. Or we need an :math:`or`, to
+implement alternatives (``|``). None of that is rocket science.
+
+A real implementation is a bit harder, as we have to strip spaces (and comments), handle newlines, and need to keep
+track of where we are. Typically that is (nowadays) done by embedding those functions in a class; then the “input text” can be
+stored in the instance (instead of passing them constantly). That instance also has a ‘cursor’ to the current
+location.
+
+More details
+~~~~~~~~~~~~
+
+There are a lot of details that make writing a grammer complex. We mention a few, and what it effect is on the (manually
+written) code.
+
+When using alternatives (the ``|`` operator in the grammar), a PEG-parser will always try the first alternative first,
+Only when that fails, it back-ups an try the next alternative. Sometimes means (almost) start again, and parse the same file almost
+completely again. Therefore the *packrat* algorithm is usually used; using memoization.
+|BR|
+This is not hard: just add a few lines of boilerplate before and after each call. To store intermediate partial-ast(s) in a
+cache.
+
+Sometimes, we like to use another parser-strategy, like LALR_ (used by Yacc_), GLR_ (e.g Bison, the successor of Yacc_)
+or `LL(k)`_ (introduced by ANTLR, which was popular for a while); each one has it pros and cons.  Still, all (or almost)
+start with the same grammar (although smarter strategies may result is shorter, easier to maintain [#maintain]_
+grammars) [#notation]_.
+
+For a long time PEG-parsers where not able to handle left recursive rules [#leftStack]_. Until somebody discovered that is not
+correct. Grammars in Castle can be left recursive! Both direct and indirect recursion is allowed.
+
+.. tabs::
+
+   .. code-tab:: PEG Direct recursion
+
+      expr <- expr '-' term | term
+
+   .. code-tab:: PEG Indirect recursion
+
+      A <- B "a" | "a"
+      B <- A "b" | "b"
+
+   .. code-tab:: PEG A rewritten grammar
+
+      expr <- term ( '-' term )*
+
+.. note::
+
+   It is always possible to rewrite a lef-recursief grammar to one that isn’t. However, that make the grammar harder to
+   read & maintain (for humans). It does also influence the outcome; the tree will differ.
+
+   By example, an simple calculation as :math:`7-5-3` should result in :math:`((7-5)-3)` but that needs left
+   recursion. When rewriting it, you must be carefull not to get :math:`(7-(5-3))`!
+   |BR|
+   This can be fixes, by adding an extra step. But it is better to use the update PEG-strategy: Just add more boilerplate code!
+
+   For that reason Castle will support recursion! You can write the grammar as you need, as we are generating that extra
+   boilerplate anyhow.
+
+
+Generating the code
+===================
+
+You might recognise the pattern: To make the grammer more useful, the algorithms become more complex and adds more
+code. This “extra” code, however is not hard; you just need the same (or almost the same) lines at many places.
+|BR|
+This begs for automation. And that is exactly what most compiler-compilers do.
+
+A compiler-compilers read the grammar and generates the code. As shown above it will generate (C, C++, C#, Java,
+Python, or ...) functions [#OrTables]_ that call each-other. It will also detect left-recursion, and might compensate for
+that. The result: more boilerplate-code; but as it is automatically generated this is easy.
+
+Classic tools
+-------------
+There are many tools, that we can use for inspiration. A short overview, and how it influences Castle.
+
+Possible the most famous compiler-compilers is Yacc_. It was developed in 197X and generates C-code that can be compiled
+and linked to your code. To parse a string, you had to call ``yyparse())``.  It would however be relatively simple to
+generate functions with the name of each rule, using the same machinery. In that decade however, the goal was
+differently. Memory was limited, what we can also see in the used grammar: one had to craft it carefully as the was no
+back-tracking an only a single token look-ahead.
+
+Bison_ is Gnu reimplementation of Yacc_, but can use several parsing-algorithms.cLike Yacc_, it used a separate Lexer_:
+*flex* (whereas Yacc uses *lex*).  A lexer_ splits the input-string into a stream of *Tokens* using another (simpler,
+but faster) algorithm. In that time that was relevant.
+|BR|
+As a lexer_ can be implemented with a parsing-algorithm (but not the other-way around), and as the need for speed doesn't
+demand a separate lexer_ anymore; modern parsings are often “scannerless”. This removes the need to use two meta-syntaxes
+(for the lexer/scanner and the parser) and so is simpler to use.
+|BR|
+Also Castle use a scannerless approach.
+
+Castle: rules are functions
+===========================
+
+.. resolution:: In Castle each rule act as a *callable*
+   :ID: R_GrammerCallables
+   :links: U_Grammers
+
+   Each parse-rule that is defined in Castle is a kind of function; more accurately it’s a “callable”
+
+Also in Castle you can use grammars; but now directly in your program, using the Castle-syntax. And Castle will generate
+“code” --Castle-functions that is. But now without an extra tool.
+|BR|
+This “generate code” is not ‘code as text’. Why should we generate code, to read & parse it back and compile it
+directly? It easier to generate the AST, that would be the result of parsing the generated-code, directly.
+
+But the effect is the same. You create a set of function with this generic “text to tree” signature, by writing some
+simle rule. Castle does the rest for you. Easy!
+
+And in case you are wondering how to use actions is in e.g. YACC: You don’t (need them). See :ref:`G2C-actions` for why
+there are outdated and both :ref:`matching-statements`, and :ref:`CyclicWoods`
+
+
+----------
+
+.. rubric:: Footnotes
+
+.. [#func]
+   Instead of a **function**, it can also be a *method, or any *callable*. We use ‘function’ a generic term, in the
+   mathematical meaning: some input (parameters) and an output (return value).
+
+.. [#maintain]
+   This is not specially for grammers; all it valid for all programming-languages. New languages may introduce new
+   concepts (like --once-- OO). When the compiler becomes smarter, the programmer can focus in the important bits!
+
+.. [#notation]
+   Aside of multiple parser-algorithms, there are also several notation to write the grammar itself; like `EBNF
+   <https://en.wikipedia.org/wiki/Extended_Backus–Naur_form>`__  `ABNF
+   <https://en.wikipedia.org/wiki/Augmented_Backus–Naur_form>`__, and `YACC`_
+   Most implementations of a given algorithm, use a dialect of a standard one, to enable :ref:`G2C-actions`, or ..
+
+   Also Caste does this: We use the Caste-grammer, which is based on both EBNF and PEG; but using the classic ‘|’
+   instead of the ‘\’ for ordered-choice.
+
+.. [#leftStack]
+   Without going into details left-recursion is hard for many parsing-algorithms. In the shown approach, a
+   rule-function (for a rule that is direct left-recurse) will call itself as first step. In this way no progress is
+   made, and the stack will quickly overrun.
+
+.. [#OrTables]
+   Some tools, like Yacc by example, use another approach. Instead of many functions it has a generic (run-time) library
+   that used code-tables; which are generated by the tool. Still, that is just a implementation detail.
+
+.. _LALR:  https://en.wikipedia.org/wiki/LALR_parser
+.. _LALR(1): LALR_
+.. _GLR:   https://en.wikipedia.org/wiki/GLR_parser
+.. _LL(k): https://en.wikipedia.org/wiki/LL_parser
+.. _YACC:  https://en.wikipedia.org/wiki/Yacc
+.. _Bison: https://en.wikipedia.org/wiki/GNU_Bison
+.. _Lexer: https://en.wikipedia.org/wiki/Lexical_analysis

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/3.NoActions.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/3.NoActions.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,149 @@
+.. include:: /std/localtoc.irst
+
+.. _G2C-actions:
+
+===================
+No *inline* actions
+===================
+
+.. post:: 2022/05/21
+   :category: Castle, DesignStudy
+   :tags: Castle, Grammar
+
+   In :ref:`grammmar-code` we have mentioned that many compiler-compilers reuse the Yacc invention “actions”. And we
+   hinted already that Castle prefers an alternative.
+
+   Let’s see why the old concept is outdated ... And what is easier to use.
+
+Actions, in retrospect
+======================
+
+When parsing an input with the aspiration to verify the input does matches the grammar only; a result as :math:`True` or
+:math:`False` will do. Commonly this is *not* our goal; we want to act on the input. Or at least *read* the content.
+|BR|
+`Yacc`_ invented *actions*: embedded (C-) code-fragments that are copied into the generated parser. When the parser
+reached that point the code as executed. You could anything you like: Build a parse-tree, or directly act on the
+(partially) parsed input [#SAXDOM]_.
+
+It was great (back then). Many, also the more modern, parser-generators use inline-actions -- with the drawback that it
+makes the grammer harder to read.  In spite of the popularity of actions, I think we can do better, as lot has happend
+since then. Most important: parsing-algorithms become a lot smarter. Yacc_ used a simple `LALR(1)`_ pattern; with only 1
+token lookahead. That allowed us to execute an action as soon a the input was read upto that point. Without backtracking
+and other “considere alternatives”, that execution is always deterministic.
+
+Ambiguity
+---------
+
+With *“backtracking”* (and other *smartness*) this has chanced. Both the compiler-compiler and the resulting parsers
+have to consider multiple ways on how to read the input. And may reconsider many tokens and lines later on how to parse
+a (earlier) line. When execution actions “in-line”, the can become executed many times -- which probably isn’t what was
+ment when specifying the grammer.
+
+Many strategies exist to solve this ambiguity.  Some tools demand that each action have no side-effects. When a
+pure-functions (as the are called) many times, the deliver exactly the same result, every time. So the issue is gone;
+albeit it limits you in what your actions can do -- strictly speaking even printing a debug message is not allowed.
+Others use this effect and cache the first result and reuse the next time(s). Again it works, but it limits on what
+actions can do!
+|BR|
+A tools may also postpone all actions until the parser is confident on how to read (parse) the input -- often when all
+input is read. Again it works, unless you expected (debug) output on the fly.
+
+In short: inline-actions have become more restricted and less useful when parser become smarter. Without solving the
+need for maintainable grammers.
+
+Memory
+------
+
+Once memory was very restricted; a compiler-compiler that only needed a single token-lookahead was using not more memory
+then needed. When needed, the programmer could use inline-actions to build the “parse-tree” on the fly. This has become the
+standard. During parsing one builds a tree: a parse-tree. And often we postproces it afterwards [#SAXDOM]_.
+
+As modern tools need to (be able to) read the whole input anyhow to be able parse it, and the memory-issues is solved
+[#fun]_, the need to process “actions” *inline* is gone. But we need a design to act in the input!
+
+
+Visitors
+========
+
+The de-facto solution is **vistitors**. Remember, back-them the `Visitor Pattern`_ wasn't invented yet! But now
+visitors_ are very popular to separates algorithms and data. We like to build the “parse-tree” in one component first
+and, act on it with visitors_ (and friend) later; possible in another component.
+
+.. hint:: Visitors & friends
+
+   There are many kinds of visitors; most (sub)patterns are very interwoven with the language that is used -- although
+   many programming-language do no have “build in” support for this pattern. It the developer who has to write all.
+
+   In classic OO-languages, one write specially named methods in a class. That are called using single (or double)
+   dispatch; to handle the data-object ‘D’ the method `visit_D()` is called “automagically”. And for a subclass ‘S’ one
+   has to implement `visit_S()` -- even when it should do exactly the same as `visit_D()`; no inheritance here.
+
+   Other languages, like CSS, use visitors_ slightly differently. Here `“selectors”
+   <https://en.wikipedia.org/wiki/CSS#Selector>`__ are use to *select* a part of a tree on which a scripts-alike
+   “declaration” will act. One can even select multiple parts; the system will interate over them automatically.
+   |BR|
+   Also `XLST <https://en.wikipedia.org/wiki/XSLT>`_ uses this approach; here `XPATH
+   <https://en.wikipedia.org/wiki/XPath>`__ expressions are used to select the data.
+   |BR|
+   This kind of visitor needs language-support: to be able to separate which data is to be pick and which actions has to
+   be performed on all found parts.
+
+
+   Most likely there are even more variants of this pattern (and even within the OO-languages, various version
+   exist). For me, and for now, it are all “**visitors** (or *friends*)”.
+   |BR|
+   Castle will have a more advanced version; as it should be easy for developer (and hard to make mistakes).
+
+
+Castle Has build-in visitors
+============================
+
+.. resolution::  Castle Grammers should not need “inline-actions”
+   :ID: RG_NoInlineActions
+
+   The traditional inline actions, as one invented by Yacc_, are outdated as the complicate the grammer, modern
+   parser-strategies need to read all input anyhow and we aren’t that restricted in memory anymore. So, an alternative
+   that make the code better maintainable is to be preferred.
+
+   .. tip:: It does not imply Castle (or a future version) is not allowed to support inline-actions
+
+      Grammer-tules are just functions; so why not allow pseudo-rules, that act as inline-actions, but are just regular
+      functions (with the same signature)
+
+.. Use::  Castle Grammers can use Visitors
+   :ID: UG_GrammerVisitors
+
+   To act on data, and to separate the data and the action, Castle will support Visitors that can act on Grammers; or
+   more accurate: on the trees that result from a parser-invocation.
+
+   .. tip:: To enable this, Castle has a (generic, abstract) data-type ``Tree``; see :ref:`tree-type`.
+
+   With (parser)visitors, it should be possible to “select” a (set of) tree-part(s), and “call” an some code that will
+   act on that data. Typically, that “code” will be a function (or other callable), but it can also be a lambda, or a
+   “code block”.
+
+----------------------------
+
+.. rubric:: Footnotes
+
+.. [#SAXDOM]
+   With hindsight we can compare this how we handled and are handling XML (and/or HTML) now.
+
+   It started with `SAX`_: “events” that act as small *actions* as soon that part was read/parsed (remember: pasting XML
+   is simple as the tags denote the tree). Nowadays, everybody is using the `DOM`_: the whole input is converted to a
+   tree first (the `DOM`_) and *visitor-alike* “scripts” will process this `DOM`_ afterwards.
+
+.. [#fun]
+   Just for fun: Guess, what is bigger: All source-code of the complete Linux-kernel, or one (high definition) movie?
+
+
+.. _YACC:  https://en.wikipedia.org/wiki/Yacc
+.. _SAX:   https://en.wikipedia.org/wiki/Simple_API_for_XML
+.. _DOM:   https://en.wikipedia.org/wiki/Document_Object_Model
+
+
+.. _LALR:     https://en.wikipedia.org/wiki/LALR_parser
+.. _LALR(1):  LALR_
+
+.. _Visitor Pattern:   https://en.wikipedia.org/wiki/Visitor_pattern
+.. _Visitors:          `Visitor Pattern`_

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/5.FSM-syntax.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/5.FSM-syntax.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,442 @@
+.. include:: /std/localtoc.irst
+
+.. _eval_FSMs-syntax:
+
+=========================
+FSM syntax, an evaluation
+=========================
+
+.. post:: 2022/06/10
+   :category: Castle, Design
+   :tags: Castle, FSM
+
+   As described in :ref:`FSMs-are-needed` *Finit State Machines* are great and needed -- even tough no (main) programming
+   language has syntax support for it. But there are other (computer) language that (more-or-less) support the
+   corresponding `State pattern`_.
+   |BR|
+   By example plantUML --very populair by mature developers-- has a syntax to draw them.
+
+   What can we learn from them? That is the topic of this post, before we define the Castle syntax.
+
+
+Goal: Short & Maintainable
+**************************
+
+Before we can define the (Castle) syntax for FSM_\s, we should know where we are aiming for. We need to support “all”
+kinds of FSM, as required by [:need:`U_FSM_Syntax`] and refined by [:need:`U_FSM_extensions`]; e.g. the syntax should
+allow non-determinism. And like all parts of Castle: maintainability and preventing mistakes is important.
+|BR|
+For a FSM this means **short**: avoid boilerplate-code.
+
+The FSM_\`s mathematical model is simple: a set of `states` (‘:math:`S`’), the input `events` (‘:math:`E`’),
+the transaction `rules` (‘:math:`R`’), a `start-state` (‘:math:`S0`’), and the `final-states` -- which are not needed
+for a SW-FSM [#final-action]_. Usually, a set of `actions` (‘:math:`A`’) is required too. Where this set is implicitly
+defined: the actions are listed inside the rules.
+|BR|
+Each `rule` is relation :math:`R := S * E -> S, A`; this “table” is typically the biggest part of an FSM.
+
+So, to make a FSM-code compact, we have to focus on the rules.  It’s tempting to regard this rule-set as a *matrix*:
+with (‘:math:`S`’) and (‘:math:`E`’) on the axes and the next-states [#non-determinism]_ (and actions) inside each
+cell. Nevertheless this matrix is huge and probably sparse: most cells are empty, as the combination does not occur.
+|BR|
+We can describe such a sparse-matrix by listing the cell-value with the coordinates. This boils-down to listing the
+rules, one by one .The disadvantage of this that many states and/or events are listed many times. As we will see below,
+some languages solve this by factor-out `states` and/or `events`.
+
+.. hint:: Concurrency is not relevant
+
+   FSM’s can be huge in code but do not need a lot of computer-power. For every *step* --one input-- one state-variable
+   has to be updated, and the action has to be triggered. That action can be “big” (an can need concurrency), the FSM
+   itself not. Therefore, the syntax of the FSM doesn't need special attention to make the FSM concurrent.
+
+
+Languages that support the state-pattern
+****************************************
+
+Some tools support FSMs, the state-pattern, or something that resembles it. We will not evaluate the tool, but focus in
+the “input” those tools use. And on what concept we can reuse to design the syntax/grammar that Castle will use for
+FSM-support.
+
+PlantUML
+========
+
+.. include:: FSM-sidebar-plantUML.irst
+
+The design-tool plantUML support the UML-FSM_ State diagram with a quite compact syntax. The focus however is on
+*drawing* [#plantUML-arrows]_. As one can add text ‘on’ the arrows and ‘in’ the states, events and actions can be
+specified. However, the is no specific syntax for that. By example, many add text like :code:`event / action()` to
+annotate the transaction with events and actions. But for plantUML it us just text. The same for Moore-actions: It an
+convention to add them to a state, with prefixes as **E:** and **L:**.
+|BR|
+So using this syntax directly isn’t possible. By adding a bit or (formal) grammar is easy.
+
+PlantUML support all aspects of the UML-FSM_, including super/sub-states (plantUML calles them ‘Composite state’) and
+concurrent states. As ‘drawing’ is the main goal, support for :math:`\epsilon`\-transaction, all kind of actions, etc is
+solved as described above: by text.
+
+Super/Sub-states
+----------------
+Substates are drawn ‘inside’ a superstate. This is described with a nested structure; a state can have an (optional)
+``{} block``. Inside that block, the same syntax is uses as for the main FSM_.
+
+This part of syntax does not fit the goals of Castle; as it is still *one* piece of code; it does not make the source
+“shorter” [#indirect]_. But more important: one would typically like to reuse “sub FSM” and specify those details
+later/elsewhere in the program.
+
+Referring
+~~~~~~~~~
+
+A developer like to *refer* to other parts; by example to import other modules or *name* those. Not by recode them. This
+is not possible (relevant) in plantUML’s state diagrams. Although some do/try by separate the source into multiple
+files, and use the “``!include`` preprocessing” options -- a bit like good-old C textual includes. One misses namespaces
+and other *modern* features however.
+
+.. _SMC:
+
+SMC (State Machine Compiler) & friends
+======================================
+
+.. include:: FSM-sidebar-SMC.irst
+
+There are many versions of the “State Machine Compiler”. Most use a text-input-file to specify a FSM_ and *’compile’*
+that into programm-code first. Then the normal compiler is used to compile it “asis”.
+|BR|
+We do not discuss the tools itself, but will examine the input-file. And (when given) the formal grammar.
+
+Uncle Bobs’s version
+---------------------
+
+Uncle Bob’s version basically uses a “table” with 4 columns: ``current.state``, ``event``, ``next.state``, ``action``;
+separated by whitespace. The name of the FSM, and it initial state are written-down above the tabel. This table is
+translated into a class with a nested-switch FSM [#generated]_; the SW-developer should create a subclass that
+implements actions (as methods).
+|BR|
+As SMC will generated the essential code (which should be deterministic), the FSM needs to be deterministic; the syntax
+does allow (a bit of) non-determinism however. But by example *epsilon*- (and especially *‘instantly’*) transaction are not
+possible.
+
+It is possible to factor-out some current.states (but not events) by using ``{}-blocks`` --the docs speak about
+*“convenient syntactic sugar”*. Equally, one can combine several actions (function-calls) into one: surround
+them with braces.
+|BR|
+This block concept can also be use to describe “abstract states”, which resembles super/sub-states. This is done by the
+``:``\-modifier postfixing a state, and putting the  abstract-state-name between
+parenthesis.
+|BR|
+It is also possible to specify entry/leave(exit) action, again by postfixing a state with :samp:`‘<’ {entry-action}`
+or/and :samp:`‘>’ {exit-action}`.
+
+The basic syntax is quite simple and readable; although whitespace as separator is not ideally --also as it make it a bit
+unclear (hard to remember) what the order is. This readability issues becomes bigger when factoring-out (and the number
+of columns decrease), or using state-modifiers.
+|BR|
+This can easily be improved (for Castle), by adding a bit more grammar-sugar and have several ‘tokens’ between the columns.
+
+The sytax of this version of SMC allows somethings that resembles hierarchically superstates; although the hierarchy is
+“inlined”.
+|BR|
+For Castle, we cherish the ability to spilt the text over multiple files [#hierarchically-split]_.
+
+
+SMC (sourceforge) version
+-------------------------
+
+This version is derived from an early variant of (Uncle) Bob Martin’s (see above), according to its `documentation
+<http://smc.sourceforge.net/SmcManual.htm>`__ The basic input-syntax is equally; although a lot “target-language details
+are added to the header (like file-names etc)-- for Castle this is not relevant.
+
+The syntax is updated. By example, to describe Moore  actions the keywords `Entry` and `Leave` are used with
+``{}-blocks`` surrounding the action (even for a single call). In general, those ``{}-blocks`` has become compulsory;
+every state has such a block., as has every action. This makes the syntax more regulair and readable for C/etc
+programmers.
+|BR|
+But all those braces makes that the compact “table alike” structure for the rules is gone.
+
+guards & parameters
+~~~~~~~~~~~~~~~~~~~
+
+A new feature is **“guards”**: a boolean expression-postfix on events (in square-Brackets: ``[<guard>]``). The specified
+transaction will only happen when and that event happens and the guard is true. The same event without a guard will act
+as a kind of default/fall-through transaction.
+
+Another feature are **event-parameters** (called “Transition Arguments”; as the words event and transition are not used
+consistently). In all examples this event-parameter is used in the guard; it’s not clear (Nore relevant) the tool can
+also use it elsewhere.
+
+
+more changes
+~~~~~~~~~~~~
+
+It support also a few notations, that do (IMHO) not fit in the FSM_ notion; like having a stack (that makes it a
+stack-machine or `PDA <https://en.wikipedia.org/wiki/Pushdown_automaton>`__). But it has a nice feature to generate
+(graphviz) diagrams; this really is convenient for the developer. Even one nowadays probably would prefer to see plantUML
+State diagrams, as they are more standard.
+
+And again, for castle we like to be able to “distribute” details over multiple files.
+
+.. _SCXML:
+
+State Chart XML (SCXML): State Machine Notation for Control Abstraction
+=======================================================================
+
+.. include:: FSM-sidebar-SCXML.irst
+
+SCXML is a (XML-based) standard “language” [#voice]_ to describe (more-or-less) an UML-FSM_.
+|BR|
+Surely, the XML-part is not applicable for Castle. Still, XML describes a tree (structure) -- like the Castle text
+format will be converted into an AST (so, also a tree). So there we can learn (or at least try).
+
+This format treads *events* as attributes of a transition. See the disadvantage of this in `Remarks (general)`), below.
+
+Harel StateCharts (aka UML-FSM_) are supported. Both by being able to nest states; using the power of XML: Any
+``<state>`` elements may have (other) ``state`` elements as children. And by having ``<parallel>`` elements, that can
+contain (multiple) ``<state>`` elements -- here, each of those parallel states act as a “small FSMs” that are all active
+when the parent state is active. This is an elegant way to describe “Orthogonal regions” (aka “Concurrent states”).
+
+Concurrent sub-states
+---------------------
+
+Like a regulair ``<state>``, a ``<parallel>`` element has an ID (attribute), that act as name -- showing a bit of
+similarity between normal states and concurrent-substates. This approach can be usable for Castle.
+
+Possible, two concurrent states can also be seen in a hierarchical way. At the top level is just one state, that is
+active or not. And when we dive into de details, it *can* have substates (like normal a hierarchy); only here some
+states can be active concurrently. As SCXML describes it, the “upper” state (nor the rest of the FSM) does not have to
+know about this concurrency.
+|BR|
+Additionally, those concurren “substates” do not *exist*, whe the upper state is passive ...
+
+.. tip:: Have to give this a tought ...
+
+   When ``state`` can act a small FSM_ internally, we can possible define a “concurrent state class” too. That class
+   act as state, and can have “two” (or more) FSM’s inside ...
+
+   The inheritance-order/tree becomes complex however;  `Liskov
+   <https://en.wikipedia.org/wiki/Liskov_substitution_principle>`__  should not be violated.
+
+   *  ``FSM`` is s subtype of ``state``. (as a state, is only active or not).
+   * The “concurrent one`` is also a subtype of ``state``, not containing some  ``FSM``\s
+
+   *Or, should we not inherited, but always aggregate? Sometimes 1, sometimes more...*
+
+
+No Referring
+------------
+Although XML has many options to refer other docs, SCXML does use none... Except for one place; the “G.1” example in the
+w3-specification refers to another (scxml-) file, using XInclude! Without any explaining text nor semantics. I guess the
+semantics is like  a textual preprocessor: all text in that file should be read as if it was typed-in. That does not
+help (me) [#google]_.
+
+
+Some other relevant languages
+*****************************
+
+There are more tools (and there input languages) that can inspire us. They do not directly define a FSM_, but can be
+used to visualize it, or use FSMs as part of the languages.
+
+DOT/graphviz
+============
+
+.. sidebar:: Links
+
+   * `https://en.wikipedia.org/wiki/DOT_(graph_description_language)
+     <https://en.wikipedia.org/wiki/DOT_(graph_description_language)>`__
+   * https://en.wikipedia.org/wiki/Graphviz
+   * https://www.graphviz.org
+
+DOT is language --introduced & used by tool Graphviz-- to describe (mathematical) graphs. It’s a very flexible language:
+both undirected and directed “edges”  between “nodes” are possible; one can describe trees “woods” and more, which can
+be cyclic (or not). When introduced (together with the autorouters graphviz), over 30 years ago, it hit the marked ...
+|BR|
+Suddenly we could describe & show anything ... Including state-diagrams.
+
+DOT, as a language, can’t define a FSM -even we can show the state-transitions. And nowadays one would prefer plantUML
+(which used graphviz) to that.
+|BR|
+But it has learned us that state-transition (arrows, or edges in a graph) can be described in text as simple as
+:samp:`{current} --> {next}`.  A syntax we will reuse in Castle.
+
+.. _Dezyne:
+
+Verum’s Dezyne
+==============
+
+.. sidebar:: Links
+
+   - https://dezyne.org
+   - https://gitlab.com/dezyne
+   - https://verum.com/discover-dezyne/
+   - https://dezyne.org/dezyne/manual/dezyne/html_node/A-Simple-State-Machine.html
+
+Dezyne (now open-source) is a programming language (with a set of tools) to implement (embedded) controll software. One
+can also create state-machines with it. So that part of the language can inspire Castle.  We use `this Tutorial
+<https://dezyne.org/dezyne/manual/dezyne/html_node/A-Simple-State-Machine.html>`__ example as reference.
+
+In this example the `behavior` is described in an (mostly) `“Imperative”
+<https://en.wikipedia.org/wiki/Imperative_programming>`__ (normal) style of programming [#dezyne-semantics]_, mixed with
+events (``on`` keywords) and guards (:samp:`[{bool-expr}]`, like above). Therefore this simple FSM is implemented in a
+phraseology that is very close to the nested-switch one. The outer switch is replaced by pillar of guards (The lines starting
+with ``[]`` can we top-levels cases); the inner switch by ``on`` “event-handler”.
+
+|BR|
+Not shown in this example, but one use the reverted style (as far as I know).
+
+In away, it also resembles the “factor the state out” style as described above in the “tables” -- although de developer
+has to use an assign-statement to change state; unlike above where naming the new state will do [#dezyne-state]_.
+|BR|
+Assuming one can use the “reverted” (nested-switch) style too, it is in Dezyne possible to (“in a way”) factor-out the
+inputs (instead of the state). None of the examples above where able to this.
+
+For Castle, if (and only if) we enable this factor-out option (even when we do not endorse it), I would prefer to have
+this symmetry (as in Dezyne): one can factor-out both state and/or inputs! As shown in the example, the syntax for both
+switches is a differs a bit. By such a  contrast in syntax, its become cleare wich “ID” is state an which one it de
+“input”. And thus we can allow to swap the order, and so, it becomes possible to factor-out both. #Nice
+
+BTW, Dezyne uses both “declarative” and “imperative” statements. As we describe in :ref:`Declarative-programming` Castle
+will promote this declarative style; it’s great to declare a FSM (over implement it in an imperative style). And I have
+no glue why Dezyne made another choice...
+
+Ragel
+=====
+
+.. sidebar:: Links
+
+   - https://en.wikipedia.org/wiki/Ragel
+   - http://www.colm.net/open-source/ragel/
+   - https://en.wikipedia.org/wiki/Thompson%27s_construction
+
+Ragel is also a FSM-compiler, but unlike SMC_ is does not need ``rules`` as input. It uses RegExps as input!
+|BR|
+There is not a lot of documentation on the input however. But is has a interesting approach.
+
+It looks like one can define “paths” [#path-vs-step]_ by specifying some RegExps. Regel builds a NFA_ by using
+`Thompson's construction algorithm <https://en.wikipedia.org/wiki/Thompson%27s_construction>`__, out of those
+RegExps. So, the developer doesn't need tho specify which ``states`` nor ``rules`` are needed; only all the allowed
+paths (or routes). 
+
+Actions are also possible. They are “added” to the route (but do not consume input, so like a
+:math:`\epsilon`-transition.
+
+
+Remarks (general)
+******************
+Based on the evaluation of these tools/languages, we can make some general remarks. Especially where relevant for the
+design of the syntax of Castle.
+
+Transitions & Symmetry
+======================
+
+Many tools use a syntax (and/or terminology) that is not inline with the (original) FSM_ (mathematical) model;
+especially for a “transition”:
+|BR|
+(We ignore the ``actions`` for a while, here).
+
+* Tools like SMC_ and SCXML_ see **the transition** as *“the arrow between 2 states”*  The input-event is then like a
+  attribute of that transition.
+  |BR|
+  So we have ``states`` and ``transition``.
+
+* Whereas others -- like Dezyne_ and plantUML_\--   (and the theory) sees **transitions** as *the relation between 3
+  parts*: from ``state``  and ``input (event)`` toward the  next ``state``.
+  |BR|
+  So we have  ``states``, ``inputs/events`` and ``transitions`` (or rules).
+
+The implication of “employing an events as attribute of a transition”, is that one can factor-out states, but nog events
+anymore. Wheres when using ``state`` and ``event`` as more symmetrical pair; one can factor-out either the state, *or*
+the event -- as shown in e.g. the “revered” code example.
+
+* The (basic) UncleBob’s version of SMC uses this more symmetrical model -- which leads to compact table.
+  |BR|
+  But as the whitespace formating, does not allow to change the order of state/event; only factoring-out over the 1ste
+  is possible.
+
+Hierarchy
+=========
+
+Several formats do kind-of embrace the hierarchical states, but only in an inline-notation. Which effectively cancel the
+effect of hierarchy. A figure that displays states “nested” inside states (as plantUML can produce) is showning
+hierarchy. But not the kind of hierarchy that we need/like to construct a complex FSM_
+
+To construct a hierarchical FSM, we like to:
+
+#. Define a “main” FSM with states in one place
+#. Consider each (or some) state of that (upper) FSM as “lower” sub-FSMs itself
+#. Add (later, and “in another file”) sub-states by adding details to *only* that state.
+#. Are able to add more and more details, by “redefining” a state as small FSM in itself.
+
+Independent of those “isolated details”, it would be nice when ‘Castle’ can flaten-out the hierarchy and draw the
+“nested” variant. Or even beter: can display a partial flattened-out one; depending on the focus the developer has on
+that comment.
+
+Compactness
+===========
+
+Inline with the general need as described in :ref:`Declarative-programming`, we can already conclude that a declarative
+style for FSM_\s is more compact then a imperative style where one (also) ahs to specify some implementation details
+(like: assigning the next state).
+
+A style as used in Ragel_ --to specify paths, not steps--, is potential even more compact. Especially when the input are
+characters -- which is not ge the general case.
+|BR|
+It may be also one step to far, as in MAYA (Most Advanced Yet Acceptable).
+
+
+-------
+
+.. rubric:: Footnotes
+ 
+.. [#final-action]
+   The final-states are used by mathematics to verify/accept an input. Whereas a SW-FSM is typically used to control a
+   system; and run *forever*. When a “final state” is needed in a SW-FSM, typical a “final-action” is used.
+
+.. [#non-determinism]
+   Remember, we have to support non-determinism! Each cell in the matrix can have multiple “next states” (and
+   corresponding actions).
+
+.. [#plantUML-arrows]
+   By example: the *arrows* in plantUML can have varions lengths (`->` , `-->`, `--->`) to hint plantUML how to draw;
+   this has no (functional) meaning. This is very conviant for a *drawing tool*, not for a programming-language.
+
+.. [#indirect]
+   This is not completely correct. By ‘nesting’ one has the advantages of sharing higher rules.
+
+.. [#generated]
+   This is generated code, and should not be touched. Therefor the maintainability-issue does not occur; just
+   re-renerate the class!
+
+.. [#hierarchically-split]
+   IMHO the goal of the hierarchy is to be able to split the “source” of the main-state/FSM and the
+   detailed-states. Developers are used to devide functionality over modules/components -- and so text-files. And
+   practice this every time details are added.
+
+.. [#voice]
+   As a practical limitation one should mention that both the standard and may examples have a voice (over IP)
+   background. Which makes the understandability for the *general* case a bit hard.
+
+.. [#google]
+   When `googling for scxml + xinclude <https://www.google.com/search?q=scxml+xinclude>`__ one find a few hits. Like
+   the comment/question “is it an omission” (as it was descriped in a draft), or “is it removed” from the spec (and
+   *forgotten* to update the example)?
+   |BR|
+   There is no clear answer, but is appears that `XInclude` is kind of a general XML-facility; that have to be applied
+   first (before using scxml). Which resembles the preprocessor. So I give up [#xml-more]_
+
+.. [#xml-more]
+   I was kind of hoping that one coud refer to a part in another file. Like we have a common “library” scxml-file and
+   use (the definitions of) a few “states” in that file. Apparently not ...
+
+.. [#dezyne-semantics]
+   Notice that the style of Dezyne resembles (or “feels as”) imperative programming, but the semantics do differ!
+
+.. [#dezyne-state]
+   Dezyne has no “states” (at tupe/words) -- at least not in the found FSMs. Is create state by assigning value to
+   variable; that act as stare (like in C). Probably one can use the Enum type to define (simulate) state; but still one
+   has to assign that value to a variable.
+
+.. [#path-vs-step]
+   In a  FSM (diagram) there are “steps” to go from one state to another. A “path” is a sequence of such a steps. 
+   
+.. _FSM:		https://en.wikipedia.org/wiki/Finite-state_machine
+.. _State pattern: 	https://en.wikipedia.org/wiki/State_pattern
+.. _UML-FSM:		https://en.wikipedia.org/wiki/UML_state_machine
+.. _NFA:		https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/5b.short_FSM-vs-Grammar.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/5b.short_FSM-vs-Grammar.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,24 @@
+FSMs vs Grammars
+=================
+
+In case you are wondering: *“Are FSMs and Grammars related, or the same?”*
+
+The are related, but not equal.
+
+As discovered by `Chomsky <https://en.wikipedia.org/wiki/Noam_Chomsky>`__ there is a `hierarchy <https://en.wikipedia.org/wiki/Chomsky_hierarchy>`__ of languages (or actually grammars).  As Chomsky was studying all kind of languages, include natural “human” language, his perception differs from our interpretation.  |BR| When we (SW/Engineers) speak about grammars, we typically refer to “Context free grammars” (`CFG <https://en.wikipedia.org/wiki/Context-free_grammar>`__) -- Chomsky classify them as “Type-2”.
+
+A non-deterministic PushDown machine (`PDA <https://en.wikipedia.org/wiki/Pushdown_automaton>`__) is needed to
+recognise a “Type-2” (CFG) Grammar. (Which is a simple version of a stack-machine, which is lot more restricted then a Turing Machine).
+|BR|
+And as a FSM is one of the most restricted machines that exist --it can recognise only “Type-3” `Regular grammar
+<https://en.wikipedia.org/wiki/Regular_grammar>`__-- a FSM can’t be used to recognise a (CFG) grammar.
+
+.. seealso::
+
+   .. postlist::
+      :category: Castle
+      :tags: FSM
+
+   .. postlist::
+      :category: Castle
+      :tags:  Grammar

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/8.ConcurrentComputingConcepts.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/8.ConcurrentComputingConcepts.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,489 @@
+.. include:: /std/localtoc2.irst
+
+.. _ConcurrentComputingConcepts:
+
+=============================
+Concurrent Computing Concepts
+=============================
+
+.. post:: 2022/09/30
+   :category: Castle DesignStudy
+   :tags: Castle, Concurrency
+
+   Sooner as we realize, even embedded systems will have piles & heaps of cores, as I described in
+   “:ref:`BusyCores`”. Castle should make it easy to write code for all of them: not to keep them busy, but to maximize
+   speed up [useCase: :need:`U_ManyCore`]. I also showed that threads_ do not scale well for CPU-bound (embedded)
+   systems. Last, I introduced some (more) concurrency abstractions. Some are great, but they often do not fit
+   nicely in  existing languages.
+   |BR|
+   Still, as Castle is a new language, we have the opportunity to select such a concept and incorporate it into the
+   language.
+
+   In this blog, we explore a bit of theory. I will focus on semantics and the possibilities to implement them
+   efficiently. The exact syntax will come later.
+
+Basic terminology
+=================
+
+Many theories are available, as are some more practical expertise, regrettably hardly non of them share a common
+vocabulary.  For that reason, I first describe some basic terms, and how they are used in these blogs. As always, we use Wikipedia
+as common ground and add links for a deep dive.
+|BR|
+Again, we use ‘task’ as the most generic term for work-to-be-executed; that can be (in) a process, (on) a thread, (by) a
+computer, etc.
+
+.. include:: CCC-sidebar-concurrency.irst
+
+Concurrent
+----------
+
+Concurrency_ is the **ability** to “compute” multiple *tasks* at the same time.
+|BR|
+Designing concurrent software isn’t that complicated but; demands another mindset than when we write software that does
+one task after the other.
+
+A typical example is a loop: suppose we have a sequence of numbers and we like to compute the square of each one. Most
+developers will loop over those numbers, get one number, calculate the square, store it in another list, and continue.
+It works, but we have also instructed the computer to do it in sequence. Especially when the task is a bit more
+complicated, the compiler does know whether the ‘next task’ depends on the current one, and can’t optimize it.
+
+A better plan is to tell the compiler about different tasks. Most are independent: square a number. There is also one
+that has to be run at the end: combine the results into a new list. And one is a bit funny: distribute the elements over
+the “square tasks”. Clearly one has to start with this one, but it can be concurrent with many others too.
+|BR|
+This is *not* a parallel algorithm. When not specifying the order, we allow parallel execution. We do not demand it,
+sequential execution is allowed too.
+
+
+Parallelism
+-----------
+
+Parallelism_ is about executing multiple tasks (seemingly) at the same time. We will on focus running many multiple
+concurrent tasks (of the same program) on *“as many cores as possible”*.  When we assume a thousand cores, we need a
+thousand independent tasks (at least) to gain maximal speed up. A thousand at any moment!
+|BR|
+It’s not only about doing a thousand tasks at the same time (that is not too complicated, for a computer) but also —
+probably: mostly — about finishing a thousand times faster…
+
+With many cores, multiple “program lines” can be executed at the same time, which can introduce unforeseen effects:
+changing the same variable, accessing the same memory, or competing for new, “free” memory. And when solving that, we
+introduce new hazards: like deadlocks_ and even livelocks_.
+
+
+Distributed
+~~~~~~~~~~~
+
+A special form of parallelism is Distributed-Computing_: computing on many computers. Many experts consider this
+an independent field of expertise. Still --as Multi-Core_ is basically “many computers on a chip”-- it’s an
+available, adjacent [#DistributedDiff]_ theory, and we should use it, to design our “best ever language”.
+
+
+.. include:: CCC-sidebar-CS.irst
+
+Communication Efficiently
+=========================
+
+When multiple tasks run concurrently, they have to communicate to pass data and control progress. Unlike in a
+sequential program -- where the control is trivial, as is sharing data-- this needs a bit of extra effort.
+|BR|
+There are two main approaches: shared-data of message-passing; we will introduce them below.
+
+Communication takes time, especially *wall time* [#wall-time]_ (or clock time), and may slow down computing. Therefore
+communication has to be efficient. This is an arduous problem and becomes harder when we have more communication, more
+concurrency, more parallelism, and/or those tasks are short living. Or better: it depends on the ratio of
+time-between-communications and the time-between-two-communications.
+
+
+Shared Memory
+-------------
+
+In this model all tasks (usually threads or processes) have some shared/common memory; typically “variables”. As the access
+is asynchronous, the risk exists the data is updated “at the same time” by two or more tasks. This can lead to invalid
+data and so Critical-Sections_ are needed.
+|BR|
+This is a very basic model which assumes that there is physical memory that can be shared. In distributed systems this
+is uncommon, but for threads it’s straightforward.
+
+An advantage of shared memory is the fast *communication-time*. The wall-time and CPU-time are roughly the same: the
+time to write & read the variable added to the (overhead) time for the critical section --  which is typically the
+bigger part.
+|BR|
+The big disadvantage of this model is that is hazardous: The programmer needs to insert Critical_Sections into his code
+at all places that *variable* is used. Even a single access to a shared variable, that is not protected by a
+Critical-Section_, can (will) break the whole system [#OOCS]_.
+
+
+Messages
+--------
+
+A more modern approach is Message-Passing_: a task sends some information to another; this can be a message, some data,
+or an event. In all cases, there is a distinct sender and receiver -- and apparently no common/shared memory-- so no
+Critical-Sections [#MPCS]_ are needed; at least not explicitly. Messages are easier to use and more generic: they can be
+used in single-, multi-, and many-core systems. Even distributed systems are possible -- then the message (and its data)
+is serialised, transmitted over a network, and deserialised.
+
+As you may have noticed, there is an analogy between Message-Passing_ and Events_ (in an event-loop). They have separate
+histories but are quite similar in nature. Like a “message”, the “event” is also used to share data (& control) to
+isolated “tasks”.
+
+.. warning::
+
+   Many people use the networking mental model when they think about Message-Passing_, and *wrongly* assume there is
+   always serialisation (and network) overhead. This is not needed for parallel cores as they typically have shared
+   (physical) memory.
+
+   Then, we can use the message abstraction at developer-level, and let the compiler translate that into shared
+   memory instructions for the processor level.
+   |BR|
+   Notice: As the compiler will insert the (low level) Semaphores_, the risk that a developer forgets one is gone!
+
+
+.. include:: CCC-sidebar-MA-links.irst
+.. _MPA:
+
+Messaging Aspects
+=================
+
+There are many variants of messaging, mostly combinations of some fundamental aspects. Let mentions some basic ones.
+
+(A)Synchronous
+--------------
+
+**Synchronous** messages resemble normal function calls. Typically a “question” is sent, the call awaits the
+answer message, and that answer is returned. This can be seen as a layer on top of the more fundamental send/receive
+calls. A famous example is RPC_: the Remote Procedure Call.
+
+**Asynchronous** messages are more basic: a task sends a message and continues. That message can be “data”, an “event”,
+a “command”, or a “query”. Only in the latter case, some response is essential. With async messages, there is no desire
+to get the answer immediately.
+
+As an example: A task can send many queries (and/or other messages) to multiple destinations at once, then go into
+*listen-mode*, and handle the replies in the order they are received (which can be different than as sent). Typically,
+this speeds up (wall) time, and is only possible with async messages. Notice: the return messages need to carry an “ID”
+of the initial messages to keep track -- often that is the query itself.
+
+
+(Un)Buffered
+------------
+
+Despite it is not truly a characteristic of the message itself, messages can be *buffered*, or not. It is about
+the plumbing to transport the message: can this “connection” (see below) *contain/save/store* messages?  When there is no
+storage at all the writer and reader need to rendezvous: send and receive at the same (wall) time.
+|BR|
+With a buffer (often depicted as a queue) multiple messages may be sent before they need to be picked up by the
+receiver; the number depends on the size of the buffer.
+
+Note: this is always asymmetric; messages need to be sent before they can be read.
+
+Connected Channels (or not)
+---------------------------
+
+Messages can be sent over (pre-) *connected channels* or to freely addressable end-points. Some people use the term
+“connection-oriented” for those connected channels, others use the term “channel” more generic and for any medium that
+is 
+transporting messages. I try to use “*connected-channel”*  when is a *pre-connected* channel.
+
+When using connected channels, one writes the message to the channel; there is no need to add the receiver to the
+message. Also when reading, the sender is clear.
+|BR|
+Clearly, the channel has to be set up before it can be used.
+
+Without connected channels, each message needs a recipient; often that receiver is added (“carried”) to the message
+itself.
+|BR|
+A big advantage is, that one does not need to create channels and end-points first -- which especially counts when a low
+number (possible one) of messages are sent to the same receiver, and/or many receivers exist (which would lead to a huge
+number of channels).
+
+
+(Non-) Blocking
+---------------
+
+Both the writer and the reader can be *blocking* (or not); which is a facet of the function-call. A blocking reader it
+will always return when a message is available -- and will pause until then.  Equally, the write-call can block: pause
+until the message can be sent -- e.g. the reader is available (rendezvous) or a message buffer is free.
+
+When the call is non-blocking, the call will return without waiting and yield a flag whether it was successful or not.
+Then, the developer will commonly “cycle” to poll for a profitable call; and let the task do some other/background work
+as well.
+
+Futures (or promises)
+~~~~~~~~~~~~~~~~~~~~~
+
+A modern variant of non-blocking makes use of “Futures_”. The call will always return this opaque data structure
+immediately. It may be a blank -- but the procedure can continue. Eventually, that data will be filled in “by the
+background”. It also contains a flag (like ``done``), so the programmer can check (using an if) [#future-CS]_ whether
+the data is processed.
+
+
+Uni/Bi-Directional, Many/Broad-cast
+-----------------------------------
+
+Messages can be sent to one receiver, to many, or even to everybody. Usually, this is modeled as a characteristic of the
+channel. At the same time, that channel can be used to send messages in one or two directions.
+
+It depends on the context of the exact intent. For example in (TCP/IP) `networking, ‘Broadcasting’
+<https://en.wikipedia.org/wiki/Broadcasting_(networking)>`__ (all not point-to-point variants) focus on reducing the
+amount of data on the network itself. In `distributed computing ‘Broadcasting’
+<https://en.wikipedia.org/wiki/Broadcast_(parallel_pattern)>`__ is a parallel design pattern. Whereas the `‘Broadcast’
+flag <https://en.wikipedia.org/wiki/Broadcast_flag>`_ in TV steaming is completely different: is it allowed to save
+(record) a broadcast...
+
+We use those teams with a functional aim. We consider the above-mentioned RCP connection as **Unidirectional** -- even
+the channel can carry the answer. When both endpoints can take the initiative to send messages, we call it
+**Bidirectional**.
+|BR|
+With only 2 endpoints, we call the connection **Point-to-Point** (*p2p*). When more endpoints are concerned, it’s
+**Broadcast** when a message is sent to all others (on that channel), and **Manycast** when the user (the programmer) can
+(somehow) select a subset.
+
+
+Reliability & Order
+-------------------
+
+Especially when studying “network messages”, we have to consider Reliability_ too. Many developers assume that a send
+message is always received and that when multiple messages are sent, they are received in the same order. In most
+traditional --single-core-- applications this is always the chase. With networking applications, this is not always
+true.  Messages can get lost, received out of order, or even read twice. Although it is always possible to add a
+“reliability layer”.
+|BR|
+Such a layer makes writing the application easier but introduces overhead too. And therefore not always the right
+solution.
+
+In Castle, we have “active components”: many cores are running parallel, all doing a part of the overall (concurrent)
+program. This resembles a networking application -- even while there is no real network -- where at least three nodes
+are active.
+
+This is a bit more complicated, so let us start with an example. Say, we have 3 components ``A``, ``B1``, and
+``B2``. All are connected to all others. We assume that messages are unbuffered, non-blocking, never got lost, and that
+two messages over the same channel are never out-of-order. Sound simple, isn’t it?
+|BR|
+Now state that ``A`` send a message (`m1`) to ``B1`` and then one (`m2`) to ``B1``. The “B components”  will --on
+receiving a message from ``A`` -- send a short message to the other one (`m3` and `m4`). And that message triggers
+(again both in ``B1`` and ``B2``) to send an answer to ``A``; so `m5` and `m6`.
+
+Now the question is: in which order those answers (in ``A``) are received? The real answer is: **You don’t know!**
+|BR|
+It’s clear that ``A`` will get `m5` and `m6` -- given that all messages (aka channels) are reliable. But there are many
+ways those messages may receive in the opposite order. Presumably, even in more ways, than you can imagine. For example,
+``B1`` might process `m4` before it processes `m1`! This can happen when channel ``A->B1`` is *slow*, or when ``B2``
+gets CPU-time before ``B1``, or...
+
+When we add buffering, more connected components, etc this *“network”* acts less reliable than we might aspect (even
+though each message is reliable). When we add some real-time demands (see below), the ability to use/model a solution
+using an unreliable message becomes attractive ...
+|BR|
+It’s not that you should always favor unreliable, out-of-order messages. Without regard, No! We are designing a new
+language, however --one that should run efficiently on thousands of core, in a real-time embedded system-- then the
+option to utilize them may be beneficial.
+
+
+.. hint::
+
+   As a simple example to demonstrate the advantage of an “unreliable connection”, let us consider an audio (bidirectional)
+   connection, that is not 100% reliable.
+   |BR|
+   When we use it “as is”, there will be a bit of noise, and even some hick-ups. For most people, this is acceptable,
+   when needed they will use phrases such as *“Can you repeat that?”*.
+
+   To make that connection reliable, we need checksums, low-level confirmation messages, and once in a while have to send
+   a message again. This implies some buffering (at both sides), and so the audio stream will have a bit of delay.
+   This is a  common solution for unidirectional PODcasts, and such.
+
+   For a bidirectional conversation, however, this buffering is not satisfactory. It makes the *slow*, people have to wait
+   on each other and will interrupt one other.
+   |BR|
+   Then, a *faster* conversation with a bit of noise is commonly preferred.
+
+
+Process calculus & more
+=======================
+
+After studying many concurrent concepts, we need to address one more, before we can *design* the Castle language. That is
+“*How do we determine what is ‘best’ (ever)*”?  Can we *calculate* the performance of every aspect? The answer is no;
+but there are formal systems that can help: Process-Calculus_ (or -Algebra).
+|BR|
+Unfortunately, there are many of them. And I like to avoid the recursions-trap: study them all, find a meta-calculus
+to determine the best, etc.
+
+So let us give a quick overview. And recall, the term ‘process’ is pretty general: it denotes the *behavior of a
+system*, not the more limited practice most software developers use.
+
+.. include:: CCC-sidebar-calc-demo.irst
+
+Mathematical models
+-------------------
+
+Many Process-Calculus_\es are invented around 1980. As often, those traditional ones focus on the issues that were current
+back then. And although they are still useful, they might be unaware of modern aspects of computing -- like huge code
+bases, and over a thousand cores.
+
+Petri Ne
+~~~~~~~~~
+
+Probably the oldest mathematical model to describe distributed systems is the Petri-Net_, invented in 1962 -- some claim
+it even started in 1939(!).  In its graphical representation, it looks like a network of circles (‘places’) and bars,
+(‘actions’) connected by arrows (‘arcs’). It also contains ‘tokens’ -- zero or more dots inside a circle. They can
+flow through the network and kind of represent the (global) state.
+|BR|
+There is an extensive, complex mathematical model behind this. Which makes Petri-Net_\s very powerful.
+
+A drawback however is, that all tokens have to move to the next place at the same time. When using Petri-Net_\s as a
+calculus, this is not an issue. But it becomes impossible to execute that in a distributed (or Multi-Core) environment,
+or a base of a language.
+
+Communicating sequential processes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CSP_ is probably the best-known *formal* language to describe (patterns in) concurrent systems. It started in 1978 as a
+kind of programming language and has evolved since then.  Occam_ --the language to program the once famous Transputer_--
+is based on CSP_.
+
+Also ‘Go_’ (the language) is influenced by CSP_. A sign the CSP_ isn’t too old.
+
+Calculus of Communicating Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CCS_ is also quite old (1980) and quite useful to calculate  deadlocks_ and livelocks_
+
+Algebra of Communicating Processes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Also, ACP_ dates back from 1982 and is a real algebra -- it probably contrived the general term Process-Calculus_. Like
+any algebra, it has (transformation) “rules” [#bool-algebra]_.
+|BR|
+By those *rules*, one can convert (“transform”) a process of concurrent and/or sequential actions into other, equivalent
+processes -- and prove they are the same (or nor). And look for patterns that should not (never) happen; like deadlocks_
+and livelocks_.
+
+I like this algebra aspect, as we can use it inside some :ref:`Castle-Tools` to validate the design is sound.
+
+Π-calculus
+~~~~~~~~~~
+
+Pi-Calculus_ is a more recent (1992) addition to the family of Process-Calculus_\es. It allows some dynamic behavior;
+like transmitting the names of the channel -- which facilitates the growth & reconfiguration of the network during execution.
+|BR|
+That expect, for example, is needed for the :ref:`CC-example-Sieve`.
+|BR|
+It also shows some of the shortcomings of “traditional” models, as hinted above.
+
+As it is a small (but expressive) “language”, that resembles λ-calculus a bit, it has some omissions too: no numbers,
+no functions, not even an `if-statement` (all quite fundamental for a programming language).  It is based on **names**,
+which mirror both *variables* and *channels*.
+
+.. _CCC-Actors:
+
+The Actor Model
+---------------
+
+The Actor-Model_ is strictly speaking not a Process-Calculus_, but it has many similarities. A big dissimilarity is its
+inspiration; where a Process-Calculus_ are based on mathematics, the Actor-Model_ is inspirited by physics. See
+Calculus-vs-Actors_ for more on their (dis)similarities.
+|BR|
+The Actor-Model_ began in 1973, matured in the '80s, and become fashionable when “cloud computing” started. There are
+many “bold-on” actor packages for almost all popular languages. They focus mostly on *robust, scalable, distributed
+applications*; less on the speed-up of a single program.  Still, the :ref:`”Many-Core” concept<CC>` we use for Castle
+is closely related.
+
+Being inspired by physics, which is concurrent by nature, the perception differs. An *actor* is local, “active”, and
+independent. It can only act on the messages that it receives, sent new messages, and/or create new actors. It (typically)
+has an internal state, but that is completely internal (or *private*, as developers call it).
+|BR|
+There is no global state, no central synchronisation, no “shared memory”, and no (overall) orchestration. Everything is
+decentral.
+
+One can model many well-known software systems as an Actor-Model_: like email, SOAP, and other web services. Also,
+interrupt-handling can be modeled with actors: An extern message triggers the “*interrupt-handler* actor” --async of the
+main code; another *actor*-- which has to send data (aka a message) to the main actor.
+
+Another interesting dissimilarity is that the Actor-Model_, and the Actor-Model-Theory_, are also influent by
+SW-Engineering and their languages. This probably made is also convenient to design new programming languages on this
+theory.
+
+.. resolution:: Castle will use Actors as the main Concurrent Computing Concept
+   :ID: R_CCC-Actors
+   :links: U_ManyCore
+
+.. tip:: Unlike Process-Calculus_\es, there is only one Actor-Model_
+
+----------
+
+.. rubric:: Footnotes
+
+.. [#DistributedDiff]
+   There a two (main) differences between Distributed-Computing_ and Multi-Core_. Firstly, all “CPUs” in
+   Distributed-Computing_ are active, independent, and asynchronous. There is no option to share a “core” (as
+   commonly/occasionally done in Multi-process/Threaded programming); nor is there “shared memory” (one can only send
+   messages over a network).
+   |BR|
+   Secondly, collaboration with (network-based) messages is a few orders slower than (shared) memory communication. This
+   makes it harder to speed up; the delay of messaging shouldn't be bigger than the acceleration when doing things in
+   parallel.
+   |BR|
+   But that condition does apply to Multi-Core_ too. Although the (timing) numbers do differ.
+
+.. [#wall-time]
+   As a reminder: We speak about *CPU-time* when we count the cycles that make a core busy; so when a core is waiting, no
+   CPU-time is used. And we use *wall-time* when we time according to  “the clock on the wall”.
+
+.. [#OOCS]
+   The brittleness of Critical-Sections_ can be reduced by embedding (the) (shared-) variable in an OO abstraction. By
+   using *getters and *setters*, that control the access, the biggest risk is (mostly) gone. That does not, however,
+   prevent deadlocks_ or livelocks_.
+   |BR|
+   And still, all developers have to  be disciplined to use that abstraction ... *always*.
+
+.. [#MPCS]
+   This is not completely correct; Message-Passing_ can be implemented on top of shared memory. Then, the implementation
+   of this (usually) OO-abstraction contains the Critical-Sections_; a bit as described in the footnote above.
+
+.. [#timesCPU]
+   And the overhead will grow when we add more cores. Firstly while more “others” have to wait (or spin), and secondly
+   that the number of communications will grow with the number of cores too.  As described in the :ref:`sidebar
+   <Threads-in-CPython>` within :ref:`BusyCores` solving this can give more overhead than the speed we are aiming for.
+
+.. [#future-CS]
+   Remember: to be able to “fill in” that Future-object “by the background” some other thread or so is needed. And so, a
+   Critical-Section_ is needed. For the SW-developer the interface is simple: read a flag (e.g. ``.done()``. But using
+   that too often can result in a slow system.
+
+.. [#anycast]
+   Broadcasting_ is primarily known for “network messages”; where it has many variants -- mostly related to the
+   physical network abilities, and the need to save bandwidth. As an abstraction, they can be used in “software messages”
+   (aka message passing) too.
+
+.. [#bool-algebra]
+   Those ‘rules’ resembles the boolean algebra, that most developers know: `NOT(x OR y) == NOT(x) AND NOT(y)`. See
+   Wikipedia for examples of ACP_.
+
+.. _ACP:			https://en.wikipedia.org/wiki/Algebra_of_communicating_processes
+.. _Actor-Model-Theory:		https://en.wikipedia.org/wiki/Actor_model_theory
+.. _Actor-Model:		https://en.wikipedia.org/wiki/Actor_model
+.. _Broadcasting:		https://en.wikipedia.org/wiki/Broadcasting_(networking)
+.. _CCS:			https://en.wikipedia.org/wiki/Calculus_of_communicating_systems
+.. _CSP:			https://en.wikipedia.org/wiki/Communicating_sequential_processes
+.. _Calculus-vs-Actors:		https://en.wikipedia.org/wiki/Actor_model_and_process_calculi
+.. _Concurrency:		https://en.wikipedia.org/wiki/Concurrency_(computer_science)
+.. _Critical-Section:		https://en.wikipedia.org/wiki/Critical_section
+.. _Critical-Sections:		Critical-Section_
+.. _Distributed-Computing:	https://en.wikipedia.org/wiki/Distributed_computing
+.. _Events:			https://en.wikipedia.org/wiki/Event_(computing)
+.. _Futures: 			https://en.wikipedia.org/wiki/Futures_and_promises
+.. _Go:				https://en.wikipedia.org/wiki/Go_(programming_language)
+.. _Message-Passing:		https://en.wikipedia.org/wiki/Message_passing
+.. _Multi-Core:			https://en.wikipedia.org/wiki/Multi-core_processor
+.. _Occam: 			https://en.wikipedia.org/wiki/Occam_(programming_language)
+.. _Petri-Net:			https://en.wikipedia.org/wiki/Petri_net
+.. _Pi-Calculus: 		https://en.wikipedia.org/wiki/Π-calculus
+.. _Process-Calculus:		https://en.wikipedia.org/wiki/Process_calculus
+.. _RPC:			https://en.wikipedia.org/wiki/Remote_procedure_call
+.. _Reliability:		https://en.wikipedia.org/wiki/Reliability_(computer_networking)
+.. _Semaphores:			https://en.wikipedia.org/wiki/Semaphore_(programming)
+.. _Spinlocking:		https://en.wikipedia.org/wiki/
+.. _Threads:			https://en.wikipedia.org/wiki/Thread_(computing)
+.. _Transputer:			https://en.wikipedia.org/wiki/Transputer
+.. _deadlocks:			https://en.wikipedia.org/wiki/Deadlock
+.. _livelocks:			https://en.wikipedia.org/wiki/Deadlock#Livelock
+.. _parallelism:		https://en.wikipedia.org/wiki/Parallel_computing
+.. _pthreads: 			https://en.wikipedia.org/wiki/Pthreads

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/CCC-sidebar-CS.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/CCC-sidebar-CS.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,31 @@
+.. -*-rst-*-
+   included in  `8.BusyCores-concepts.rst`
+
+.. sidebar:: About Critical Sections
+
+   For those, who are not familiar with Critical-Sections_ or Semaphores_, here is a short intro.
+
+   .. rubric:: Dilemma: Statements are  not atomic.
+
+   Unlike some developers presume, *“code lines”* are not *‘atomic’*: they can be interrupted. When using (e.g.) threads_,
+   the “computer” can pause one thread halfway through a statement to run another one temporally and continue a millisecond
+   later. When it happens during writing or reading a variable, and the other thread also accesses the same shared-memory,
+   the result is unpredictable. To prevent that, we need to control the handling of that variable: make it a
+   Critical-Section_.
+
+   .. rubric:: Solve it by marking sections *‘exclusive’*.
+
+   Essentially, we need to tell the “computer” that a line (or a few lines) is *atomic*. To enforce the access is
+   exclusive, the compiler will add some fundamental instructions (specific for that type of CPU) to assure this. A
+   check is inserted just before the section, which can suspend the thread when another task is in the CS. When access
+   is granted, a bit of bookkeeping is needed -- so that the “check” in other threads will halt). That bookkeeping is
+   updated when leaving, along with more bookkeeping to un-pause the suspended threads.
+
+   .. rubric:: Complication: overhead!
+
+   As you can imagine, this “bookkeeping” is extra complicated on a Multicore system; some global data structure is
+   needed, which is a Critical-Section_ in itself.
+   |BR|
+   There are many algorithms to solve this. All with the same disadvantage: it takes a bit of time -- possible by
+   “Spinlocking_” all other cores (for a few nanoseconds). As Critical-Sections a usually short (e.g. one assignment, or
+   a few lines) the overhead can be (relatively) huge [#timesCPU]_!

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/CCC-sidebar-MA-links.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/CCC-sidebar-MA-links.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,56 @@
+.. -*-rst-*-
+   included in  `8.BusyCores-concepts.rst`
+
+.. sidebar:: More on Messages
+
+   There are two ways to look at messages: *“vertically”* [#V]_ or *“horizontally”* [#H]_. The first concentrates on the
+   endpoint: How does a programmer use the (API) interface? Alternatively, one can concentrate on the channel between the
+   endpoints --ignoring lower implementation details.
+
+   More in this, and all kinds of aspects, and many more views can be found --as usual-- on Wikipedia.
+
+   .. tabs::
+
+      .. tab:: Endpoints
+
+         Words such as *synchronous*, *asynchronous* (and the popular ``async`` keyword) can have many intents -- all more or less
+         related (on basic fundamental theories) but can be very dissimilar in practical applications. Besides, most theories assume a
+         *communication* background, not a (software) engineering one, and certainly not an abstraction -- but still, it is a sound base.
+
+         * `Asynchrony Computer Programming 	<https://en.wikipedia.org/wiki/Asynchrony_(computer_programming)>`_
+         * `Asynchronous communication 		<https://en.wikipedia.org/wiki/Asynchronous_communication>`_
+         * `Synchronous serial communication 	<https://en.wikipedia.org/wiki/Synchronous_serial_communication>`_
+         * `Synchronisation (as a generic term)	<https://en.wikipedia.org/wiki/Synchronization>`_
+
+      .. tab:: Channels
+
+         Some aspects are more related to the *channel* used to transmit the message than how end-points act.
+
+         Traditionally, *blocking* used to be applied to I/O operations.  Nowadays, it’s more generic: how to behave
+         when immediate execution is impossible. Although often, IO is involved deep down -- ``printf`` is an example;
+         it will *pauze* until the line can be published, ot there is space in a buffer.
+
+         * `Communication channel		<https://en.wikipedia.org/wiki/Communication_channel>`_
+         * `Blocking				<https://en.wikipedia.org/wiki/Blocking_(computing)>`_
+         * `Buffers				<https://en.wikipedia.org/wiki/Data_buffer>`_
+         * `Reliable				<https://en.wikipedia.org/wiki/Reliability_(computer_networking)>`_
+         * `Connection-Oriented			<https://en.wikipedia.org/wiki/Connection-oriented_communication>`_
+         * `Packet-Oriented			<https://en.wikipedia.org/wiki/Packet_switching>`_
+
+      .. tab:: disambiguation
+
+         Wikipedia has more; even pages that collect pages with more:
+
+         * `Async	      				<https://en.wikipedia.org/wiki/Asynchrony>`_
+         * `Sync      					<https://en.wikipedia.org/wiki/Sync>`_
+         * `Synchronization (disambiguation)      	<https://en.wikipedia.org/wiki/Synchronization_(disambiguation)>`_
+
+
+
+   .. [#V]
+      It is called “vertical” as this interface/function will use other functions, deeper in the
+      communication-stack. So, the flow is downwards (or upwards on the other side).
+
+   .. [#H]
+      The “horizontal” direction does not follow the call-stack, but (virtually) connects two stack-levels in different
+      environments.

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/CCC-sidebar-calc-demo.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/CCC-sidebar-calc-demo.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,48 @@
+.. -*-rst-*-
+   included in  `8.BusyCores-concepts.rst`
+
+.. sidebar:: Some examples/Demos
+
+   .. tabs::
+
+     .. tab:: Petri Net
+
+        .. figure:: Wikipedia-PetriNet.gif
+
+           A trivail PetriNet; image by `Wikipedia <https://commons.wikimedia.org/wiki/File:Animated_Petri_net_commons.gif>`__
+
+     .. tab:: ACP
+
+        .. rubric:: Basic rules
+
+        .. math::
+
+           x + y &=& y + x
+
+           (x+y)+z&=& x+(y+z)
+
+           x+x&=&x
+
+           (x+y)\cdot z &=& (x\cdot z) + (y\cdot z)
+
+           (x \cdot y)\cdot z &=& x \cdot (y \cdot z)
+
+        .. rubric:: Deadlock
+
+        .. math::
+
+           \delta + x &=& x
+
+           \delta \cdot x &=& \delta
+
+        All formulas from `wikipedia <https://en.wikipedia.org/wiki/Algebra_of_communicating_processes>`__
+
+     .. tab:: Π-calculus
+
+        .. rubric:: Creation of a name
+
+        Create the *name* ``x`` that acts as a (new) communication channel. This is done *process* ``P``.
+
+        .. math:: \left(\nu x\right)P
+
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/CCC-sidebar-concurrency.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/CCC-sidebar-concurrency.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,35 @@
+.. -*-rst-*-
+   included in  `8.BusyCores-concepts.rst`
+
+.. sidebar::
+
+   .. tabs::
+
+     .. tab:: Sequential
+
+        Here, the programmer has (unwittingly) defined a sequential order.
+
+        .. code-block:: python
+
+           L2 = []
+           for n in L1:
+              L2.append(power(n))
+
+        .. note:: As ``power()`` could have side effects, the compiler **must** keep the defined order!
+
+     .. tab::  Concurrent
+
+        Now, without a specified order, the same functionality has become concurrent.
+
+        .. code-block:: python
+
+           L2 = [power(n) for n in L1]
+
+        .. note::
+
+           Although (current) python-compilers will run it sequentially, it is *allowed* to distribute it; even when
+           ``power()`` has side effects!
+           |BR|
+           As long as *python* put the results in the correct order in list ``L2`` **any order** is allowed.  “Out of
+           order” side effects are allowed by this code.
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/FSM-sidebar-SCXML.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/FSM-sidebar-SCXML.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,34 @@
+.. -*- rst -*-
+   included in  `5.eval-syntax.rst`
+
+.. sidebar::
+
+   .. tabs::
+
+      .. code-tab:: xml Example
+
+         <?xml version="1.0" encoding="UTF-8"?>
+         <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="ready">
+            <state id="ready">
+               <transition event="watch.start" target="running" />
+            </state>
+            <state id="running">
+               <transition event="watch.split" target="paused" />
+               <transition event="watch.stop" target="stopped" />
+            </state>
+            <state id="paused">
+               <transition event="watch.stop" target="stopped" />
+               <transition event="watch.unsplit" target="running" />
+            </state>
+            <state id="stopped">
+               <transition event="watch.reset" target="ready" />
+            </state>
+         </scxml>
+
+      .. tab:: Links
+
+         .. seealso::
+
+            * wikipedia https://en.wikipedia.org/wiki/SCXML
+            * W3 (specification): https://www.w3.org/TR/scxml/
+            * `Source of shown example <https://blogs.itemis.com/en/custom-code-generator-scxml>`__ (itemis blog)

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/FSM-sidebar-SMC.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/FSM-sidebar-SMC.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,84 @@
+.. -*- rst -*-
+   included in  `5.eval-syntax.rst`
+
+.. sidebar::
+
+   .. tabs::
+
+     .. tab:: SMC (example)
+        :selected:
+
+        .. code::
+
+           Initial: Locked
+           FSM: Turnstile
+           {
+             Locked    Coin    Unlocked    unlock
+             Locked    Pass    Locked      alarm
+             Unlocked  Coin    Unlocked    thankyou
+             Unlocked  Pass    Locked      lock
+           }
+
+        --- source: `Uncle Bob <https://github.com/unclebob/CC_SMC/blob/master/README.md>`__.
+        |BR|
+        Showing a basic FSM only; see the website for more examples.
+
+
+     .. tab:: Grammars (BNF)
+
+        UncleBob’s version
+
+        .. code:: BNF
+
+          <FSM>            ::=  <header>* <logic>
+          <header>         ::=  <name> ":" <name>
+          <logic>          ::=  "{" <transition>* "}"
+          <transition>     ::=  <state-spec>     <subtransition>
+                           |    <state-spec> "{" <subtransition>* "}"
+          <state-spec>     ::=  <state> <state-modifier>*
+          <state>          ::=      <name>
+                           |    "(" <name> ")"
+          <state-modifier> ::=  ":"  <name>
+                           |    "<"  <name>
+                           |    ">"  <name>
+          <subtransition>  ::   <event> <next-state> <action>
+          <action>         ::=  <name>  | "{" <name>* "}" | "-"
+          <next-state>     ::=  <state> | "-"
+          <event>          ::   <name>  | "-"
+
+        SMC (sourceforge) version [edited & shortened].
+
+        .. code:: BNF
+
+           <FSM>          ::=  <%headers> <map>+
+           <%headers>     ::=  ...Not shown here ...
+           <map>          ::=  '%map' <word> '%%' <states> '%%'
+           <states>       ::=   <word> <entry>? <exit>? '{' <transitions>* '}'
+           <entry>        ::=   'Entry {' <action>* '}'
+           <exit>         ::=   'Exit  {' <action>* '}'
+           <transitions>  ::=   <word> <args>? <guard>? <next-state> '{' <action>* '}'
+           <args>         ::=   '(' <parameter>+ ')'
+           <parameter>    ::=   <word> ':' <raw-code>
+           <guard>        ::=   '[' <raw-code> ']'
+           <next-state>   ::=   <word> |     'nil'
+           <action>       ::=   <word> '(' <arguments>* ')'
+           <raw-code>     ::=   ...Not shown here ...
+
+     .. tab:: Links
+
+        .. admonition:: UncleBobVideo version
+
+           * source:   https://github.com/unclebob/CC_SMC
+           * Grammar:  https://github.com/unclebob/CC_SMC/blob/master/README.md#BNF
+
+        .. admonition:: SMC
+
+           * source:   http://smc.sourceforge.net
+           * Tutorial: http://smc.sourceforge.net/slides/SMC_Tutorial.pdf
+           * Grammar   http://smc.sourceforge.net/SmcManAppendixA.htm
+
+        .. admonition:: other friend
+
+           * With XML-input https://github.com/jp-embedded/scxmlcc
+
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/FSM-sidebar-plantUML.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/FSM-sidebar-plantUML.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,25 @@
+.. -*- rst -*-
+   included in  `5.eval-syntax.rst`
+
+.. sidebar::
+
+   .. tabs::
+
+     .. tab:: plantUML
+
+        .. uml:: /CCastle/shared/FSM-plantUML-demo.puml
+           :scale: 78%
+
+     .. tab:: syntax
+        :selected:
+
+        .. literalinclude :: /CCastle/shared/FSM-plantUML-demo.puml
+           :lines: 5-22
+
+     .. tab:: Links
+
+        .. seealso::
+
+           * wikipedia https://en.wikipedia.org/wiki/PlantUML
+           * plantuml https://plantuml.com/state-diagram
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/Wikipedia-PetriNet.gif
Binary file CCastle/2.Analyse/Wikipedia-PetriNet.gif has changed

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Analyse/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/2.Analyse/index.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,12 @@
+====================
+Analyse & Evaluation
+====================
+
+When designing Castle, we can learn from other systems. You will find my notes here
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :glob:
+
+   *

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/5.0.eval-syntax.rst
--- a/CCastle/2.Design/eval/5.0.eval-syntax.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,442 +0,0 @@
-.. include:: /std/localtoc.irst
-
-.. _eval_FSMs-syntax:
-
-=========================
-FSM syntax, an evaluation
-=========================
-
-.. post:: 2022/06/10
-   :category: Castle, Design
-   :tags: Castle, FSM
-
-   As described in :ref:`FSMs-are-needed` *Finit State Machines* are great and needed -- even tough no (main) programming
-   language has syntax support for it. But there are other (computer) language that (more-or-less) support the
-   corresponding `State pattern`_.
-   |BR|
-   By example plantUML --very populair by mature developers-- has a syntax to draw them.
-
-   What can we learn from them? That is the topic of this post, before we define the Castle syntax.
-
-
-Goal: Short & Maintainable
-**************************
-
-Before we can define the (Castle) syntax for FSM_\s, we should know where we are aiming for. We need to support “all”
-kinds of FSM, as required by [:need:`U_FSM_Syntax`] and refined by [:need:`U_FSM_extensions`]; e.g. the syntax should
-allow non-determinism. And like all parts of Castle: maintainability and preventing mistakes is important.
-|BR|
-For a FSM this means **short**: avoid boilerplate-code.
-
-The FSM_\`s mathematical model is simple: a set of `states` (‘:math:`S`’), the input `events` (‘:math:`E`’),
-the transaction `rules` (‘:math:`R`’), a `start-state` (‘:math:`S0`’), and the `final-states` -- which are not needed
-for a SW-FSM [#final-action]_. Usually, a set of `actions` (‘:math:`A`’) is required too. Where this set is implicitly
-defined: the actions are listed inside the rules.
-|BR|
-Each `rule` is relation :math:`R := S * E -> S, A`; this “table” is typically the biggest part of an FSM.
-
-So, to make a FSM-code compact, we have to focus on the rules.  It’s tempting to regard this rule-set as a *matrix*:
-with (‘:math:`S`’) and (‘:math:`E`’) on the axes and the next-states [#non-determinism]_ (and actions) inside each
-cell. Nevertheless this matrix is huge and probably sparse: most cells are empty, as the combination does not occur.
-|BR|
-We can describe such a sparse-matrix by listing the cell-value with the coordinates. This boils-down to listing the
-rules, one by one .The disadvantage of this that many states and/or events are listed many times. As we will see below,
-some languages solve this by factor-out `states` and/or `events`.
-
-.. hint:: Concurrency is not relevant
-
-   FSM’s can be huge in code but do not need a lot of computer-power. For every *step* --one input-- one state-variable
-   has to be updated, and the action has to be triggered. That action can be “big” (an can need concurrency), the FSM
-   itself not. Therefore, the syntax of the FSM doesn't need special attention to make the FSM concurent.
-
-
-Languages that support the state-pattern
-****************************************
-
-Some tools support FSMs, the state-pattern, or something that resembles it. We will not evaluate the tool, but focus in
-the “input” those tools use. And on what concept we can reuse to design the syntax/grammar that Castle will use for
-FSM-support.
-
-PlantUML
-========
-
-.. include:: sidebar-plantUML.irst
-
-The design-tool plantUML support the UML-FSM_ State diagram with a quite compact syntax. The focus however is on
-*drawing* [#plantUML-arrows]_. As one can add text ‘on’ the arrows and ‘in’ the states, events and actions can be
-specified. However, the is no specific syntax for that. By example, many add text like :code:`event / action()` to
-annotate the transaction with events and actions. But for plantUML it us just text. The same for Moore-actions: It an
-convention to add them to a state, with prefixes as **E:** and **L:**.
-|BR|
-So using this syntax directly isn’t possible. By adding a bit or (formal) grammar is easy.
-
-PlantUML support all aspects of the UML-FSM_, including super/sub-states (plantUML calles them ‘Composite state’) and
-concurent states. As ‘drawing’ is the main goal, support for :math:`\epsilon`\-transaction, all kind of actions, etc is
-solved as described above: by text.
-
-Super/Sub-states
-----------------
-Substates are drawn ‘inside’ a superstate. This is described with a nested structure; a state can have an (optional)
-``{} block``. Inside that block, the same syntax is uses as for the main FSM_.
-
-This part of syntax does not fit the goals of Castle; as it is still *one* piece of code; it does not make the source
-“shorter” [#indirect]_. But more important: one would typically like to reuse “sub FSM” and specify those details
-later/elsewhere in the program.
-
-Referring
-~~~~~~~~~
-
-A developer like to *refer* to other parts; by example to import other modules or *name* those. Not by recode them. This
-is not possible (relevant) in plantUML’s state diagrams. Although some do/try by separate the source into multiple
-files, and use the “``!include`` preprocessing” options -- a bit like good-old C textual includes. One misses namespaces
-and other *modern* features however.
-
-.. _SMC:
-
-SMC (State Machine Compiler) & friends
-======================================
-
-.. include:: sidebar-SMC.irst
-
-There are many versions of the “State Machine Compiler”. Most use a text-input-file to specify a FSM_ and *’compile’*
-that into programm-code first. Then the normal compiler is used to compile it “asis”.
-|BR|
-We do not discuss the tools itself, but will examine the input-file. And (when given) the formal grammar.
-
-Uncle Bobs’s version
----------------------
-
-Uncle Bob’s version basically uses a “table” with 4 columns: ``current.state``, ``event``, ``next.state``, ``action``;
-separated by whitespace. The name of the FSM, and it initial state are written-down above the tabel. This table is
-translated into a class with a nested-switch FSM [#generated]_; the SW-developer should create a subclass that
-implements actions (as methods).
-|BR|
-As SMC will generated the essential code (which should be deterministic), the FSM needs to be deterministic; the syntax
-does allow (a bit of) non-determinism however. But by example *epsilon*- (and especially *‘instantly’*) transaction are not
-possible.
-
-It is possible to factor-out some current.states (but not events) by using ``{}-blocks`` --the docs speak about
-*“convenient syntactic sugar”*. Equally, one can combine several actions (function-calls) into one: surround
-them with braces.
-|BR|
-This block concept can also be use to describe “abstract states”, which resembles super/sub-states. This is done by the
-``:``\-modifier postfixing a state, and putting the  abstract-state-name between
-parenthesis.
-|BR|
-It is also possible to specify entry/leave(exit) action, again by postfixing a state with :samp:`‘<’ {entry-action}`
-or/and :samp:`‘>’ {exit-action}`.
-
-The basic syntax is quite simple and readable; although whitespace as separator is not ideally --also as it make it a bit
-unclear (hard to remember) what the order is. This readability issues becomes bigger when factoring-out (and the number
-of columns decrease), or using state-modifiers.
-|BR|
-This can easily be improved (for Castle), by adding a bit more grammar-sugar and have several ‘tokens’ between the columns.
-
-The sytax of this version of SMC allows somethings that resembles hierarchically superstates; although the hierarchy is
-“inlined”.
-|BR|
-For Castle, we cherish the ability to spilt the text over multiple files [#hierarchically-split]_.
-
-
-SMC (sourceforge) version
--------------------------
-
-This version is derived from an early variant of (Uncle) Bob Martin’s (see above), according to its `documentation
-<http://smc.sourceforge.net/SmcManual.htm>`__ The basic input-syntax is equally; although a lot “target-language details
-are added to the header (like file-names etc)-- for Castle this is not relevant.
-
-The syntax is updated. By example, to describe Moore  actions the keywords `Entry` and `Leave` are used with
-``{}-blocks`` surrounding the action (even for a single call). In general, those ``{}-blocks`` has become compulsory;
-every state has such a block., as has every action. This makes the syntax more regulair and readable for C/etc
-programmers.
-|BR|
-But all those braces makes that the compact “table alike” structure for the rules is gone.
-
-guards & parameters
-~~~~~~~~~~~~~~~~~~~
-
-A new feature is **“guards”**: a boolean expression-postfix on events (in square-Brackets: ``[<guard>]``). The specified
-transaction will only happen when and that event happens and the guard is true. The same event without a guard will act
-as a kind of default/fall-through transaction.
-
-Another feature are **event-parameters** (called “Transition Arguments”; as the words event and transition are not used
-consistently). In all examples this event-parameter is used in the guard; it’s not clear (Nore relevant) the tool can
-also use it elsewhere.
-
-
-more changes
-~~~~~~~~~~~~
-
-It support also a few notations, that do (IMHO) not fit in the FSM_ notion; like having a stack (that makes it a
-stack-machine or `PDA <https://en.wikipedia.org/wiki/Pushdown_automaton>`__). But it has a nice feature to generate
-(graphviz) diagrams; this really is convenient for the developer. Even one nowadays probably would prefer to see plantUML
-State diagrams, as they are more standard.
-
-And again, for castle we like to be able to “distribute” details over multiple files.
-
-.. _SCXML:
-
-State Chart XML (SCXML): State Machine Notation for Control Abstraction
-=======================================================================
-
-.. include:: sidebar-SCXML.irst
-
-SCXML is a (XML-based) standard “language” [#voice]_ to describe (more-or-less) an UML-FSM_.
-|BR|
-Surely, the XML-part is not applicable for Castle. Still, XML describes a tree (structure) -- like the Castle text
-format will be converted into an AST (so, also a tree). So there we can learn (or at least try).
-
-This format treads *events* as attributes of a transition. See the disadvantage of this in `Remarks (general)`), below.
-
-Harel StateCharts (aka UML-FSM_) are supported. Both by being able to nest states; using the power of XML: Any
-``<state>`` elements may have (other) ``state`` elements as children. And by having ``<parallel>`` elements, that can
-contain (multiple) ``<state>`` elements -- here, each of those parallel states act as a “small FSMs” that are all active
-when the parent state is active. This is an elegant way to describe “Orthogonal regions” (aka “Concurent states”).
-
-Concurent sub-states
---------------------
-
-Like a regulair ``<state>``, a ``<parallel>`` element has an ID (attribute), that act as name -- showing a bit of
-similarity between normal states and concurent-substates. This approach can be usable for Castle.
-
-Possible, two concurent states can also be seen in a hierarchical way. At the top level is just one state, that is
-active or not. And when we dive into de details, it *can* have substates (like normal a hierarchy); only here some
-states can be active concurrently. As SCXML describes it, the “upper” state (nor the rest of the FSM) does not have to
-know about this concurrency.
-|BR|
-Additionally, those concurren “substates” do not *exist*, whe the upper state is passive ...
-
-.. tip:: Have to give this a tought ...
-
-   When ``state`` can act a small FSM_ internally, we can possible define a “concurrent state class” too. That class
-   act as state, and can have “two” (or more) FSM’s inside ...
-
-   The inheritance-order/tree becomes complex however;  `Liskov
-   <https://en.wikipedia.org/wiki/Liskov_substitution_principle>`__  should not be violated.
-
-   *  ``FSM`` is s subtype of ``state``. (as a state, is only active or not).
-   * The “concurrent one`` is also a subtype of ``state``, not containing some  ``FSM``\s
-
-   *Or, should we not inherited, but always aggregate? Sometimes 1, sometimes more...*
-
-
-No Referring
-------------
-Although XML has many options to refer other docs, SCXML does use none... Except for one place; the “G.1” example in the
-w3-specification refers to another (scxml-) file, using XInclude! Without any explaining text nor semantics. I guess the
-semantics is like  a textual preprocessor: all text in that file should be read as if it was typed-in. That does not
-help (me) [#google]_.
-
-
-Some other relevant languages
-*****************************
-
-There are more tools (and there input languages) that can inspire us. They do not directly define a FSM_, but can be
-used to visualize it, or use FSMs as part of the languages.
-
-DOT/graphviz
-============
-
-.. sidebar:: Links
-
-   * `https://en.wikipedia.org/wiki/DOT_(graph_description_language)
-     <https://en.wikipedia.org/wiki/DOT_(graph_description_language)>`__
-   * https://en.wikipedia.org/wiki/Graphviz
-   * https://www.graphviz.org
-
-DOT is language --introduced & used by tool Graphviz-- to describe (mathematical) graphs. It’s a very flexible language:
-both undirected and directed “edges”  between “nodes” are possible; one can describe trees “woods” and more, which can
-be cyclic (or not). When introduced (together with the autorouters graphviz), over 30 years ago, it hit the marked ...
-|BR|
-Suddenly we could describe & show anything ... Including state-diagrams.
-
-DOT, as a language, can’t define a FSM -even we can show the state-transitions. And nowadays one would prefer plantUML
-(which used graphviz) to that.
-|BR|
-But it has learned us that state-transition (arrows, or edges in a graph) can be described in text as simple as
-:samp:`{current} --> {next}`.  A syntax we will reuse in Castle.
-
-.. _Dezyne:
-
-Verum’s Dezyne
-==============
-
-.. sidebar:: Links
-
-   - https://dezyne.org
-   - https://gitlab.com/dezyne
-   - https://verum.com/discover-dezyne/
-   - https://dezyne.org/dezyne/manual/dezyne/html_node/A-Simple-State-Machine.html
-
-Dezyne (now open-source) is a programming language (with a set of tools) to implement (embedded) controll software. One
-can also create state-machines with it. So that part of the language can inspire Castle.  We use `this Tutorial
-<https://dezyne.org/dezyne/manual/dezyne/html_node/A-Simple-State-Machine.html>`__ example as reference.
-
-In this example the `behavior` is described in an (mostly) `“Imperative”
-<https://en.wikipedia.org/wiki/Imperative_programming>`__ (normal) style of programming [#dezyne-semantics]_, mixed with
-events (``on`` keywords) and guards (:samp:`[{bool-expr}]`, like above). Therefore this simple FSM is implemented in a
-phraseology that is very close to the nested-switch one. The outer switch is replaced by pillar of guards (The lines starting
-with ``[]`` can we top-levels cases); the inner switch by ``on`` “event-handler”.
-
-|BR|
-Not shown in this example, but one use the reverted style (as far as I know).
-
-In away, it also resembles the “factor the state out” style as described above in the “tables” -- although de developer
-has to use an assign-statement to change state; unlike above where naming the new state will do [#dezyne-state]_.
-|BR|
-Assuming one can use the “reverted” (nested-switch) style too, it is in Dezyne possible to (“in a way”) factor-out the
-inputs (instead of the state). None of the examples above where able to this.
-
-For Castle, if (and only if) we enable this factor-out option (even when we do not endorse it), I would prefer to have
-this symmetry (as in Dezyne): one can factor-out both state and/or inputs! As shown in the example, the syntax for both
-switches is a differs a bit. By such a  contrast in syntax, its become cleare wich “ID” is state an which one it de
-“input”. And thus we can allow to swap the order, and so, it becomes possible to factor-out both. #Nice
-
-BTW, Dezyne uses both “declarative” and “imperative” statements. As we describe in :ref:`Declarative-programming` Castle
-will promote this declarative style; it’s great to declare a FSM (over implement it in an imperative style). And I have
-no glue why Dezyne made another choice...
-
-Ragel
-=====
-
-.. sidebar:: Links
-
-   - https://en.wikipedia.org/wiki/Ragel
-   - http://www.colm.net/open-source/ragel/
-   - https://en.wikipedia.org/wiki/Thompson%27s_construction
-
-Ragel is also a FSM-compiler, but unlike SMC_ is does not need ``rules`` as input. It uses RegExps as input!
-|BR|
-There is not a lot of documentation on the input however. But is has a interesting approach.
-
-It looks like one can define “paths” [#path-vs-step]_ by specifying some RegExps. Regel builds a NFA_ by using
-`Thompson's construction algorithm <https://en.wikipedia.org/wiki/Thompson%27s_construction>`__, out of those
-RegExps. So, the developer doesn't need tho specify which ``states`` nor ``rules`` are needed; only all the allowed
-paths (or routes). 
-
-Actions are also possible. They are “added” to the route (but do not consume input, so like a
-:math:`\epsilon`-transition.
-
-
-Remarks (general)
-******************
-Based on the evaluation of these tools/languages, we can make some general remarks. Especially where relevant for the
-design of the syntax of Castle.
-
-Transitions & Symmetry
-======================
-
-Many tools use a syntax (and/or terminology) that is not inline with the (original) FSM_ (mathematical) model;
-especially for a “transition”:
-|BR|
-(We ignore the ``actions`` for a while, here).
-
-* Tools like SMC_ and SCXML_ see **the transition** as *“the arrow between 2 states”*  The input-event is then like a
-  attribute of that transition.
-  |BR|
-  So we have ``states`` and ``transition``.
-
-* Whereas others -- like Dezyne_ and plantUML_\--   (and the theory) sees **transitions** as *the relation between 3
-  parts*: from ``state``  and ``input (event)`` toward the  next ``state``.
-  |BR|
-  So we have  ``states``, ``inputs/events`` and ``transitions`` (or rules).
-
-The implication of “employing an events as attribute of a transition”, is that one can factor-out states, but nog events
-anymore. Wheres when using ``state`` and ``event`` as more symmetrical pair; one can factor-out either the state, *or*
-the event -- as shown in e.g. the “revered” code example.
-
-* The (basic) UncleBob’s version of SMC uses this more symmetrical model -- which leads to compact table.
-  |BR|
-  But as the whitespace formating, does not allow to change the order of state/event; only factoring-out over the 1ste
-  is possible.
-
-Hierarchy
-=========
-
-Several formats do kind-of embrace the hierarchical states, but only in an inline-notation. Which effectively cancel the
-effect of hierarchy. A figure that displays states “nested” inside states (as plantUML can produce) is showning
-hierarchy. But not the kind of hierarchy that we need/like to construct a complex FSM_
-
-To construct a hierarchical FSM, we like to:
-
-#. Define a “main” FSM with states in one place
-#. Consider each (or some) state of that (upper) FSM as “lower” sub-FSMs itself
-#. Add (later, and “in another file”) sub-states by adding details to *only* that state.
-#. Are able to add more and more details, by “redefining” a state as small FSM in itself.
-
-Independent of those “isolated details”, it would be nice when ‘Castle’ can flaten-out the hierarchy and draw the
-“nested” variant. Or even beter: can display a partial flattened-out one; depending on the focus the developer has on
-that comment.
-
-Compactness
-===========
-
-Inline with the general need as described in :ref:`Declarative-programming`, we can already conclude that a declarative
-style for FSM_\s is more compact then a imperative style where one (also) ahs to specify some implementation details
-(like: assigning the next state).
-
-A style as used in Ragel_ --to specify paths, not steps--, is potential even more compact. Especially when the input are
-characters -- which is not ge the general case.
-|BR|
-It may be also one step to far, as in MAYA (Most Advanced Yet Acceptable).
-
-
--------
-
-.. rubric:: Footnotes
- 
-.. [#final-action]
-   The final-states are used by mathematics to verify/accept an input. Whereas a SW-FSM is typically used to control a
-   system; and run *forever*. When a “final state” is needed in a SW-FSM, typical a “final-action” is used.
-
-.. [#non-determinism]
-   Remember, we have to support non-determinism! Each cell in the matrix can have multiple “next states” (and
-   corresponding actions).
-
-.. [#plantUML-arrows]
-   By example: the *arrows* in plantUML can have varions lengths (`->` , `-->`, `--->`) to hint plantUML how to draw;
-   this has no (functional) meaning. This is very conviant for a *drawing tool*, not for a programming-language.
-
-.. [#indirect]
-   This is not completely correct. By ‘nesting’ one has the advantages of sharing higher rules.
-
-.. [#generated]
-   This is generated code, and should not be touched. Therefor the maintainability-issue does not occur; just
-   re-renerate the class!
-
-.. [#hierarchically-split]
-   IMHO the goal of the hierarchy is to be able to split the “source” of the main-state/FSM and the
-   detailed-states. Developers are used to devide functionality over modules/components -- and so text-files. And
-   practice this every time details are added.
-
-.. [#voice]
-   As a practical limitation one should mention that both the standard and may examples have a voice (over IP)
-   background. Which makes the understandability for the *general* case a bit hard.
-
-.. [#google]
-   When `googling for scxml + xinclude <https://www.google.com/search?q=scxml+xinclude>`__ one find a few hits. Like
-   the comment/question “is it an omission” (as it was descriped in a draft), or “is it removed” from the spec (and
-   *forgotten* to update the example)?
-   |BR|
-   There is no clear answer, but is appears that `XInclude` is kind of a general XML-facility; that have to be applied
-   first (before using scxml). Which resembles the preprocessor. So I give up [#xml-more]_
-
-.. [#xml-more]
-   I was kind of hoping that one coud refer to a part in another file. Like we have a common “library” scxml-file and
-   use (the definitions of) a few “states” in that file. Apparently not ...
-
-.. [#dezyne-semantics]
-   Notice that the style of Dezyne resembles (or “feels as”) imperative programming, but the semantics do differ!
-
-.. [#dezyne-state]
-   Dezyne has no “states” (at tupe/words) -- at least not in the found FSMs. Is create state by assigning value to
-   variable; that act as stare (like in C). Probably one can use the Enum type to define (simulate) state; but still one
-   has to assign that value to a variable.
-
-.. [#path-vs-step]
-   In a  FSM (diagram) there are “steps” to go from one state to another. A “path” is a sequence of such a steps. 
-   
-.. _FSM:		https://en.wikipedia.org/wiki/Finite-state_machine
-.. _State pattern: 	https://en.wikipedia.org/wiki/State_pattern
-.. _UML-FSM:		https://en.wikipedia.org/wiki/UML_state_machine
-.. _NFA:		https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/5.1.FSM_try_1.rst
--- a/CCastle/2.Design/eval/5.1.FSM_try_1.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,68 +0,0 @@
-=======================
-Castle FSM syntax tries
-=======================
-
-.. note:: Based on some experiments we select “a” language to highlight the examples.
-          Its  just try&error; there is  no relation with that language, Castle or a FSM!
-
-Try 1
-=====
-
-.. code:: ReasonML
-
-   FSM AB {
-     state A, B, C;
-
-     A + event_1  ->  state_B, action_I;
-     A + event_2  ->  state_C, action_II;
-     B + event_1  ->  state_D, action_III;
-     Z1 + event_1 ->  state_Z2;            // No action
-     Z1 + event_1 ->  ,action_only;        // Empty state: do not change
-     Z1 + event_1 ->  action_only;  // No new state
-     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
-     // Potentially it conflict with the “redundancy rule”
-     Z1 + event_1 ->  None, action_only;        // None-state: do not change
-   }
-
-Variant a
----------
-Actions with ``(`` `parameters-list` ``)``.  **Question**: Do we know those parameters here. Or are the default?
-
-.. code:: ReasonML
-
-   FSM AB {
-     state A, B, C;
-
-     A + event_1  ->  state_B, action_I(p1,p2, p3);
-     A + event_2  ->  state_C, action_II();
-     B + event_1  ->  state_D, action_III();
-     Z1 + event_1 ->  state_Z2;            // No action
-     Z1 + event_1 ->  ,action_only();        // Empty state: do not change
-     Z1 + event_1 ->  action_only();  // No new state
-     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
-     // Potentially it conflict with the “redundancy rule”
-     Z1 + event_1 ->  None, action_only();        // None-state: do not change
-
-   }
-
-
-Variant b
----------
-No  FSM/State prequel nor block
-
-.. code:: ReasonML
-
-     state A, B, C;
-
-     A + event_1  ->  state_B, action_I;
-     A + event_2  ->  state_C, action_II;
-     B + event_1  ->  state_D, action_III;
-     Z1 + event_1 ->  state_Z2;            // No action
-     Z1 + event_1 ->  ,action_only;        // Empty state: do not change
-     Z1 + event_1 ->  action_only;  // No new state
-     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
-     // Potentially it conflict with the “redundancy rule”
-     Z1 + event_1 ->  None, action_only;        // None-state: do not change
-
-
-

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/index.rst
--- a/CCastle/2.Design/eval/index.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-================
-Evaluation Notes
-================
-
-When designing Castle, we can learn from other systems. You will find my notes here
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-   :glob:
-
-   *

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/sidebar-SCXML.irst
--- a/CCastle/2.Design/eval/sidebar-SCXML.irst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,34 +0,0 @@
-.. -*- rst -*-
-   included in  `5.eval-syntax.rst`
-
-.. sidebar::
-
-   .. tabs::
-
-      .. code-tab:: xml Example
-
-         <?xml version="1.0" encoding="UTF-8"?>
-         <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="ready">
-            <state id="ready">
-               <transition event="watch.start" target="running" />
-            </state>
-            <state id="running">
-               <transition event="watch.split" target="paused" />
-               <transition event="watch.stop" target="stopped" />
-            </state>
-            <state id="paused">
-               <transition event="watch.stop" target="stopped" />
-               <transition event="watch.unsplit" target="running" />
-            </state>
-            <state id="stopped">
-               <transition event="watch.reset" target="ready" />
-            </state>
-         </scxml>
-
-      .. tab:: Links
-
-         .. seealso::
-
-            * wikipedia https://en.wikipedia.org/wiki/SCXML
-            * W3 (specification): https://www.w3.org/TR/scxml/
-            * `Source of shown example <https://blogs.itemis.com/en/custom-code-generator-scxml>`__ (itemis blog)

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/sidebar-SMC.irst
--- a/CCastle/2.Design/eval/sidebar-SMC.irst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,84 +0,0 @@
-.. -*- rst -*-
-   included in  `5.eval-syntax.rst`
-
-.. sidebar::
-
-   .. tabs::
-
-     .. tab:: SMC (example)
-        :selected:
-
-        .. code::
-
-           Initial: Locked
-           FSM: Turnstile
-           {
-             Locked    Coin    Unlocked    unlock
-             Locked    Pass    Locked      alarm
-             Unlocked  Coin    Unlocked    thankyou
-             Unlocked  Pass    Locked      lock
-           }
-
-        --- source: `Uncle Bob <https://github.com/unclebob/CC_SMC/blob/master/README.md>`__.
-        |BR|
-        Showing a basic FSM only; see the website for more examples.
-
-
-     .. tab:: Grammars (BNF)
-
-        UncleBob’s version
-
-        .. code:: BNF
-
-          <FSM>            ::=  <header>* <logic>
-          <header>         ::=  <name> ":" <name>
-          <logic>          ::=  "{" <transition>* "}"
-          <transition>     ::=  <state-spec>     <subtransition>
-                           |    <state-spec> "{" <subtransition>* "}"
-          <state-spec>     ::=  <state> <state-modifier>*
-          <state>          ::=      <name>
-                           |    "(" <name> ")"
-          <state-modifier> ::=  ":"  <name>
-                           |    "<"  <name>
-                           |    ">"  <name>
-          <subtransition>  ::   <event> <next-state> <action>
-          <action>         ::=  <name>  | "{" <name>* "}" | "-"
-          <next-state>     ::=  <state> | "-"
-          <event>          ::   <name>  | "-"
-
-        SMC (sourceforge) version [edited & shortened].
-
-        .. code:: BNF
-
-           <FSM>          ::=  <%headers> <map>+
-           <%headers>     ::=  ...Not shown here ...
-           <map>          ::=  '%map' <word> '%%' <states> '%%'
-           <states>       ::=   <word> <entry>? <exit>? '{' <transitions>* '}'
-           <entry>        ::=   'Entry {' <action>* '}'
-           <exit>         ::=   'Exit  {' <action>* '}'
-           <transitions>  ::=   <word> <args>? <guard>? <next-state> '{' <action>* '}'
-           <args>         ::=   '(' <parameter>+ ')'
-           <parameter>    ::=   <word> ':' <raw-code>
-           <guard>        ::=   '[' <raw-code> ']'
-           <next-state>   ::=   <word> |     'nil'
-           <action>       ::=   <word> '(' <arguments>* ')'
-           <raw-code>     ::=   ...Not shown here ...
-
-     .. tab:: Links
-
-        .. admonition:: UncleBobVideo version
-
-           * source:   https://github.com/unclebob/CC_SMC
-           * Grammar:  https://github.com/unclebob/CC_SMC/blob/master/README.md#BNF
-
-        .. admonition:: SMC
-
-           * source:   http://smc.sourceforge.net
-           * Tutorial: http://smc.sourceforge.net/slides/SMC_Tutorial.pdf
-           * Grammar   http://smc.sourceforge.net/SmcManAppendixA.htm
-
-        .. admonition:: other friend
-
-           * With XML-input https://github.com/jp-embedded/scxmlcc
-
-

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/eval/sidebar-plantUML.irst
--- a/CCastle/2.Design/eval/sidebar-plantUML.irst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,25 +0,0 @@
-.. -*- rst -*-
-   included in  `5.eval-syntax.rst`
-
-.. sidebar::
-
-   .. tabs::
-
-     .. tab:: plantUML
-
-        .. uml:: /CCastle/shared/FSM-plantUML-demo.puml
-           :scale: 78%
-
-     .. tab:: syntax
-        :selected:
-
-        .. literalinclude :: /CCastle/shared/FSM-plantUML-demo.puml
-           :lines: 5-22
-
-     .. tab:: Links
-
-        .. seealso::
-
-           * wikipedia https://en.wikipedia.org/wiki/PlantUML
-           * plantuml https://plantuml.com/state-diagram
-

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/index.rst
--- a/CCastle/2.Design/index.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,38 +0,0 @@
-====================
-CCastle Design Notes
-====================
-
-Castle has to be designed. Not only the “compiler”, but also the language itself. And the **“CC” concept**, And ....
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-   :glob:
-
-   */index
-   zz.todo
-
-.. note:: In case you are wondering: *“Are FSMs and Grammars related, or the same?”*
-
-   The are related, but not equal. As discovered by `Chomsky <https://en.wikipedia.org/wiki/Noam_Chomsky>`__ there is a
-   `hierarchy <https://en.wikipedia.org/wiki/Chomsky_hierarchy>`__ of languages (or actually grammars).  As Chomsky was
-   studying all kind of languages, include natural “human” language, his perception differs from our interpretation.
-   |BR|
-   When we (SW/Engineers) speak about grammars, we typically refer to “Context free grammars” (`CFG
-   <https://en.wikipedia.org/wiki/Context-free_grammar>`__) -- Chomsky classify them as “Type-2”.
-
-   A non-deterministic Push~Down machine (`PDA <https://en.wikipedia.org/wiki/Pushdown_automaton>`__) is needed to
-   recognise a “Type-2” (CFG) Grammar. (Which is a simple version of a stack-machine, which is lot more restricted then a Turing Machine).
-   |BR|
-   And as a FSM is one of the most restricted machines that exist --it can recognise only “Type-3” `Regular grammar
-   <https://en.wikipedia.org/wiki/Regular_grammar>`__-- a FSM can’t be used to recognise a (CFG) grammar.
-
-   .. seealso::
-
-      .. postlist::
-         :category: Castle
-         :tags: FSM
-
-      .. postlist::
-         :category: Castle
-         :tags:  Grammar

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/syntax/2.grammar_code.rst
--- a/CCastle/2.Design/syntax/2.grammar_code.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,231 +0,0 @@
-.. include:: /std/localtoc.irst
-
-.. _grammmar-code:
-
-===============
-Grammar is code
-===============
-
-.. post:: 2022/05/14
-   :category: Castle, DesignStudy
-   :tags: Castle, Grammar, PEG
-
-   In :ref:`Castle-CompilerCompiler` we have seen that we can define a grammar within a Castle-program. And we have
-   argued that each grammars-rule can be considered as a function.
-
-   In this post, we look into de details of how this works. And will confirm grammars is code ...
-
-Let’s start with an example. The grammer below is a simplified description of how a (PEG) parsing-rule looks like. The
-syntax in Castle is a bit more complicated, by having more details and options; but very simular. Most of the
-Caste-grammers can be parsed by the grammer below!
-
-.. code-block:: PEG
-
-   PEG_rule        <-  rule_name '<-' expression ';' ;
-   expression      <-  ordered_choice+ ;
-   ordered_choice  <-  sequence ( '|' sequence)* ;
-   sequence        <-  group | atom ;
-   group           <-  '(' expression ')' ;
-   atom            <-  rule_xref | str_lit | regexp ;
-   str_lit         <-  '"'  /[^"]*  '"' ;
-   regexp          <-  '/'  /[^/]*  '/' ;
-   rule_name       <-  ID ;
-   rule_xref       <-  ID ;
-
-With this grammer we can read and check whether an a string is a valid rule by simply calling:
-:math:`ast:=PEG\_rule(single\_line)`. When not, ``ast`` is :math:`False`, else ``ast`` has 4 children (or fields).
-Where :data:`ast[0]` represent the ``rule_name``, :data:`ast[2]` is an ``expression``; which is a sequence of
-``ordered_choice``\(s).
-|BR|
-As the rule has two constants :data:`ast[1]` and :data:`ast[3]` will always match the strings *‘<-’* and *‘;’*.
-
-
-Grammar to code
-===============
-
-Before we study how Castle *expands* a grammar to code, let examine how to do that by manually crafted code, or using a
-external compiler-compiler. In both cases, we will focus on the “validation” part only. And we skip a lot of details;
-assuming you know a bit of theory of (PEG) parser. When not, read Guido van Rossum’s excellent blog-series `PEG Parsing
-Series Overview <https://medium.com/@gvanrossum_83706/peg-parsing-series-de5d41b2ed60>`__
-
-
-Hand written code
------------------
-
-Again, let’s suppost we like to verify a string contains a *peg-rule*. Then we need some functions [#func]_, which signature
-are something like:
-
-.. tabs::
-
-   .. code-tab:: python
-
-      def PEG_rule(text: str) -> ast : ...
-      def expression(text: str) -> ast : ...
-      def ordered_choice(text: str) -> ast : ...
-      def sequence(text: str) -> ast : ...
-      ...
-
-   .. code-tab:: c
-
-      ast PEG_rule(char* txt);
-      ast expression(char* txt);
-      ast ordered_choice(char* txt);
-      ast sequence(char* txt);
-      ...
-
-Where we assume the type ``ast`` is defined in the chosen language and will be Null/None/Empty to signal :math:`False`:
-not valid.
-
-The implementation of ``PEG_rule()`` checks thats the input-string starts with a ``rule_name``, followed by the literal
-string **“<-”**, then has an ``expression`` and finally the literal string **“;”**. When one of those (four) steps fail,
-we return :math:`False`.
-|BR|
-We follow this pattern for all rules.
-
-This concept is easy to implement: each rule-function calls other rule-functions as defined by the grammar. When we
-need to check for a literal string we use :func:`expect(txt: str, literal: str) -> bool`. Also, we need a function to find
-an ID; again easy. Sometimes we need to implement a loop --to handle ``*`` and ``+``. Or we need an :math:`or`, to
-implement alternatives (``|``). None of that is rocket science.
-
-A real implementation is a bit harder, as we have to strip spaces (and comments), handle newlines, and need to keep
-track of where we are. Typically that is (nowadays) done by embedding those functions in a class; then the “input text” can be
-stored in the instance (instead of passing them constantly). That instance also has a ‘cursor’ to the current
-location.
-
-More details
-~~~~~~~~~~~~
-
-There are a lot of details that make writing a grammer complex. We mention a few, and what it effect is on the (manually
-written) code.
-
-When using alternatives (the ``|`` operator in the grammar), a PEG-parser will always try the first alternative first,
-Only when that fails, it back-ups an try the next alternative. Sometimes means (almost) start again, and parse the same file almost
-completely again. Therefore the *packrat* algorithm is usually used; using memoization.
-|BR|
-This is not hard: just add a few lines of boilerplate before and after each call. To store intermediate partial-ast(s) in a
-cache.
-
-Sometimes, we like to use another parser-strategy, like LALR_ (used by Yacc_), GLR_ (e.g Bison, the successor of Yacc_)
-or `LL(k)`_ (introduced by ANTLR, which was popular for a while); each one has it pros and cons.  Still, all (or almost)
-start with the same grammar (although smarter strategies may result is shorter, easier to maintain [#maintain]_
-grammars) [#notation]_.
-
-For a long time PEG-parsers where not able to handle left recursive rules [#leftStack]_. Until somebody discovered that is not
-correct. Grammars in Castle can be left recursive! Both direct and indirect recursion is allowed.
-
-.. tabs::
-
-   .. code-tab:: PEG Direct recursion
-
-      expr <- expr '-' term | term
-
-   .. code-tab:: PEG Indirect recursion
-
-      A <- B "a" | "a"
-      B <- A "b" | "b"
-
-   .. code-tab:: PEG A rewritten grammar
-
-      expr <- term ( '-' term )*
-
-.. note::
-
-   It is always possible to rewrite a lef-recursief grammar to one that isn’t. However, that make the grammar harder to
-   read & maintain (for humans). It does also influence the outcome; the tree will differ.
-
-   By example, an simple calculation as :math:`7-5-3` should result in :math:`((7-5)-3)` but that needs left
-   recursion. When rewriting it, you must be carefull not to get :math:`(7-(5-3))`!
-   |BR|
-   This can be fixes, by adding an extra step. But it is better to use the update PEG-strategy: Just add more boilerplate code!
-
-   For that reason Castle will support recursion! You can write the grammar as you need, as we are generating that extra
-   boilerplate anyhow.
-
-
-Generating the code
-===================
-
-You might recognise the pattern: To make the grammer more useful, the algorithms become more complex and adds more
-code. This “extra” code, however is not hard; you just need the same (or almost the same) lines at many places.
-|BR|
-This begs for automation. And that is exactly what most compiler-compilers do.
-
-A compiler-compilers read the grammar and generates the code. As shown above it will generate (C, C++, C#, Java,
-Python, or ...) functions [#OrTables]_ that call each-other. It will also detect left-recursion, and might compensate for
-that. The result: more boilerplate-code; but as it is automatically generated this is easy.
-
-Classic tools
--------------
-There are many tools, that we can use for inspiration. A short overview, and how it influences Castle.
-
-Possible the most famous compiler-compilers is Yacc_. It was developed in 197X and generates C-code that can be compiled
-and linked to your code. To parse a string, you had to call ``yyparse())``.  It would however be relatively simple to
-generate functions with the name of each rule, using the same machinery. In that decade however, the goal was
-differently. Memory was limited, what we can also see in the used grammar: one had to craft it carefully as the was no
-back-tracking an only a single token look-ahead.
-
-Bison_ is Gnu reimplementation of Yacc_, but can use several parsing-algorithms.cLike Yacc_, it used a separate Lexer_:
-*flex* (whereas Yacc uses *lex*).  A lexer_ splits the input-string into a stream of *Tokens* using another (simpler,
-but faster) algorithm. In that time that was relevant.
-|BR|
-As a lexer_ can be implemented with a parsing-algorithm (but not the other-way around), and as the need for speed doesn't
-demand a separate lexer_ anymore; modern parsings are often “scannerless”. This removes the need to use two meta-syntaxes
-(for the lexer/scanner and the parser) and so is simpler to use.
-|BR|
-Also Castle use a scannerless approach.
-
-Castle: rules are functions
-===========================
-
-.. resolution:: In Castle each rule act as a *callable*
-   :ID: R_GrammerCallables
-
-   Each parse-rule that is defined in Castle is a kind of function; more accurately it’s a “callable”
-
-Also in Castle you can use grammars; but now directly in your program, using the Castle-syntax. And Castle will generate
-“code” --Castle-functions that is. But now without an extra tool.
-|BR|
-This “generate code” is not ‘code as text’. Why should we generate code, to read & parse it back and compile it
-directly? It easier to generate the AST, that would be the result of parsing the generated-code, directly.
-
-But the effect is the same. You create a set of function with this generic “text to tree” signature, by writing some
-simle rule. Castle does the rest for you. Easy!
-
-
-----------
-
-.. rubric:: Footnotes
-
-.. [#func]
-   Instead of a **function**, it can also be a *method, or any *callable*. We use ‘function’ a generic term, in the
-   mathematical meaning: some input (parameters) and an output (return value).
-
-.. [#maintain]
-   This is not specially for grammers; all it valid for all programming-languages. New languages may introduce new
-   concepts (like --once-- OO). When the compiler becomes smarter, the programmer can focus in the important bits!
-
-.. [#notation]
-   Aside of multiple parser-algorithms, there are also several notation to write the grammar itself; like `EBNF
-   <https://en.wikipedia.org/wiki/Extended_Backus–Naur_form>`__  `ABNF
-   <https://en.wikipedia.org/wiki/Augmented_Backus–Naur_form>`__, and `YACC`_
-   Most implementations of a given algorithm, use a dialect of a standard one, to enable :ref:`G2C-actions`, or ..
-
-   Also Caste does this: We use the Caste-grammer, which is based on both EBNF and PEG; but using the classic ‘|’
-   instead of the ‘\’ for ordered-choice.
-
-.. [#leftStack]
-   Without going into details left-recursion is hard for many parsing-algorithms. In the shown approach, a
-   rule-function (for a rule that is direct left-recurse) will call itself as first step. In this way no progress is
-   made, and the stack will quickly overrun.
-
-.. [#OrTables]
-   Some tools, like Yacc by example, use another approach. Instead of many functions it has a generic (run-time) library
-   that used code-tables; which are generated by the tool. Still, that is just a implementation detail.
-
-.. _LALR:  https://en.wikipedia.org/wiki/LALR_parser
-.. _LALR(1): LALR_
-.. _GLR:   https://en.wikipedia.org/wiki/GLR_parser
-.. _LL(k): https://en.wikipedia.org/wiki/LL_parser
-.. _YACC:  https://en.wikipedia.org/wiki/Yacc
-.. _Bison: https://en.wikipedia.org/wiki/GNU_Bison
-.. _Lexer: https://en.wikipedia.org/wiki/Lexical_analysis

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/syntax/3.NoActions.rst
--- a/CCastle/2.Design/syntax/3.NoActions.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,149 +0,0 @@
-.. include:: /std/localtoc.irst
-
-.. _G2C-actions:
-
-===================
-No *inline* actions
-===================
-
-.. post:: 2022/05/21
-   :category: Castle, DesignStudy
-   :tags: Castle, Grammar
-
-   In :ref:`grammmar-code` we have mentioned that many compiler-compilers reuse the Yacc invention “actions”. And we
-   hinted already that Castle prefers an alternative.
-
-   Let’s see why the old concept is outdated ... And what is easier to use.
-
-Actions, in retrospect
-======================
-
-When parsing an input with the aspiration to verify the input does matches the grammar only; a result as :math:`True` or
-:math:`False` will do. Commonly this is *not* our goal; we want to act on the input. Or at least *read* the content.
-|BR|
-`Yacc`_ invented *actions*: embedded (C-) code-fragments that are copied into the generated parser. When the parser
-reached that point the code as executed. You could anything you like: Build a parse-tree, or directly act on the
-(partially) parsed input [#SAXDOM]_.
-
-It was great (back then). Many, also the more modern, parser-generators use inline-actions -- with the drawback that it
-makes the grammer harder to read.  In spite of the popularity of actions, I think we can do better, as lot has happend
-since then. Most important: parsing-algorithms become a lot smarter. Yacc_ used a simple `LALR(1)`_ pattern; with only 1
-token lookahead. That allowed us to execute an action as soon a the input was read upto that point. Without backtracking
-and other “considere alternatives”, that execution is always deterministic.
-
-Ambiguity
----------
-
-With *“backtracking”* (and other *smartness*) this has chanced. Both the compiler-compiler and the resulting parsers
-have to consider multiple ways on how to read the input. And may reconsider many tokens and lines later on how to parse
-a (earlier) line. When execution actions “in-line”, the can become executed many times -- which probably isn’t what was
-ment when specifying the grammer.
-
-Many strategies exist to solve this ambiguity.  Some tools demand that each action have no side-effects. When a
-pure-functions (as the are called) many times, the deliver exactly the same result, every time. So the issue is gone;
-albeit it limits you in what your actions can do -- strictly speaking even printing a debug message is not allowed.
-Others use this effect and cache the first result and reuse the next time(s). Again it works, but it limits on what
-actions can do!
-|BR|
-A tools may also postpone all actions until the parser is confident on how to read (parse) the input -- often when all
-input is read. Again it works, unless you expected (debug) output on the fly.
-
-In short: inline-actions have become more restricted and less useful when parser become smarter. Without solving the
-need for maintainable grammers.
-
-Memory
-------
-
-Once memory was very restricted; a compiler-compiler that only needed a single token-lookahead was using not more memory
-then needed. When needed, the programmer could use inline-actions to build the “parse-tree” on the fly. This has become the
-standard. During parsing one builds a tree: a parse-tree. And often we postproces it afterwards [#SAXDOM]_.
-
-As modern tools need to (be able to) read the whole input anyhow to be able parse it, and the memory-issues is solved
-[#fun]_, the need to process “actions” *inline* is gone. But we need a design to act in the input!
-
-
-Visitors
-========
-
-The de-facto solution is **vistitors**. Remember, back-them the `Visitor Pattern`_ wasn't invented yet! But now
-visitors_ are very popular to separates algorithms and data. We like to build the “parse-tree” in one component first
-and, act on it with visitors_ (and friend) later; possible in another component.
-
-.. hint:: Visitors & friends
-
-   There are many kinds of visitors; most (sub)patterns are very interwoven with the language that is used -- although
-   many programming-language do no have “build in” support for this pattern. It the developer who has to write all.
-
-   In classic OO-languages, one write specially named methods in a class. That are called using single (or double)
-   dispatch; to handle the data-object ‘D’ the method `visit_D()` is called “automagically”. And for a subclass ‘S’ one
-   has to implement `visit_S()` -- even when it should do exactly the same as `visit_D()`; no inheritance here.
-
-   Other languages, like CSS, use visitors_ slightly differently. Here `“selectors”
-   <https://en.wikipedia.org/wiki/CSS#Selector>`__ are use to *select* a part of a tree on which a scripts-alike
-   “declaration” will act. One can even select multiple parts; the system will interate over them automatically.
-   |BR|
-   Also `XLST <https://en.wikipedia.org/wiki/XSLT>`_ used this approach; here `XPATH
-   <https://en.wikipedia.org/wiki/XPath>`__ expressions are used to select the data.
-   |BR|
-   This kind of visitor needs language-support: to be able to separate which data is to be pick and which actions has to
-   be performed on all found parts.
-
-
-   Most likely there are even more variants of this pattern (and even within the OO-languages, various version
-   exist). For me, and for now, it are all “**visitors** (or *friends*)”.
-   |BR|
-   Castle will have a more advanced version; as it should be easy for developer (and hard to make mistakes).
-
-
-Castle Has build-in visitors
-============================
-
-.. resolution::  Castle Grammers should not need “inline-actions”
-   :ID: RG_NoInlineActions
-
-   The traditional inline actions, as one invented by Yacc_, are outdated as the complicate the grammer, modern
-   parser-strategies need to read all input anyhow and we aren’t that restricted in memory anymore. So, an alternative
-   that make the code better maintainable is to be preferred.
-
-   .. tip:: It does not imply Castle (or a future version) is not allowed to support inline-actions
-
-      Grammer-tules are just functions; so why not allow pseudo-rules, that act as inline-actions, but are just regular
-      functions (with the same signature)
-
-.. Use::  Castle Grammers can use Visitors
-   :ID: UG_GrammerVisitors
-
-   To act on data, and to separate the data and the action, Castle will support Visitors that can act on Grammers; or
-   more accurate: on the trees that result from a parser-invocation.
-
-   .. tip:: To enable this, Castle has a (generic, abstract) data-type ``Tree``; see :ref:`tree-type`.
-
-   With (parser)visitors, it should be possible to “select” a (set of) tree-part(s), and “call” an some code that will
-   act on that data. Typically, that “code” will be a function (or other callable), but it can also be a lambda, or a
-   “code block”.
-
-----------------------------
-
-.. rubric:: Footnotes
-
-.. [#SAXDOM]
-   With hindsight we can compare this how we handled and are handling XML (and/or HTML) now.
-
-   It started with `SAX`_: “events” that act as small *actions* as soon that part was read/parsed (remember: pasting XML
-   is simple as the tags denote the tree). Nowadays, everybody is using the `DOM`_: the whole input is converted to a
-   tree first (the `DOM`_) and *visitor-alike* “scripts” will process this `DOM`_ afterwards.
-
-.. [#fun]
-   Just for fun: Guess, what is bigger: All source-code of the complete Linux-kernel, or one (high definition) movie?
-
-
-.. _YACC:  https://en.wikipedia.org/wiki/Yacc
-.. _SAX:   https://en.wikipedia.org/wiki/Simple_API_for_XML
-.. _DOM:   https://en.wikipedia.org/wiki/Document_Object_Model
-
-
-.. _LALR:     https://en.wikipedia.org/wiki/LALR_parser
-.. _LALR(1):  LALR_
-
-.. _Visitor Pattern:   https://en.wikipedia.org/wiki/Visitor_pattern
-.. _Visitors:          `Visitor Pattern`_

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/syntax/index.rst
--- a/CCastle/2.Design/syntax/index.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-================
-About the syntax
-================
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-   :glob:
-
-   *
-

diff -r 79905a473ddb -r de487fa932d9 CCastle/2.Design/zz.todo.rst
--- a/CCastle/2.Design/zz.todo.rst	Fri Jun 10 19:18:51 2022 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-TODO (Design)
-*************
-
-Tree as std data-structure
-==========================
-
-.. todo::
-
-   * .. seealso: :ref:`matching-statements`
-
-   * Allow (aside of trees), also non-cyclic graps?
-
-   * Allow (local) “links” in the tree
-
-     - ala html: a/href
-     - ala xlm: XLINK
-     - Use XPATH/CSS alike syntax
-     - Use ‘id’

diff -r 79905a473ddb -r de487fa932d9 CCastle/3.Design/6.FSM_try_1.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/3.Design/6.FSM_try_1.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,68 @@
+=======================
+Castle FSM syntax tries
+=======================
+
+.. note:: Based on some experiments we select “a” language to highlight the examples.
+          Its  just try&error; there is  no relation with that language, Castle or a FSM!
+
+Try 1
+=====
+
+.. code:: ReasonML
+
+   FSM AB {
+     state A, B, C;
+
+     A + event_1  ->  state_B, action_I;
+     A + event_2  ->  state_C, action_II;
+     B + event_1  ->  state_D, action_III;
+     Z1 + event_1 ->  state_Z2;            // No action
+     Z1 + event_1 ->  ,action_only;        // Empty state: do not change
+     Z1 + event_1 ->  action_only;  // No new state
+     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
+     // Potentially it conflict with the “redundancy rule”
+     Z1 + event_1 ->  None, action_only;        // None-state: do not change
+   }
+
+Variant a
+---------
+Actions with ``(`` `parameters-list` ``)``.  **Question**: Do we know those parameters here. Or are the default?
+
+.. code:: ReasonML
+
+   FSM AB {
+     state A, B, C;
+
+     A + event_1  ->  state_B, action_I(p1,p2, p3);
+     A + event_2  ->  state_C, action_II();
+     B + event_1  ->  state_D, action_III();
+     Z1 + event_1 ->  state_Z2;            // No action
+     Z1 + event_1 ->  ,action_only();        // Empty state: do not change
+     Z1 + event_1 ->  action_only();  // No new state
+     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
+     // Potentially it conflict with the “redundancy rule”
+     Z1 + event_1 ->  None, action_only();        // None-state: do not change
+
+   }
+
+
+Variant b
+---------
+No  FSM/State prequel nor block
+
+.. code:: ReasonML
+
+     state A, B, C;
+
+     A + event_1  ->  state_B, action_I;
+     A + event_2  ->  state_C, action_II;
+     B + event_1  ->  state_D, action_III;
+     Z1 + event_1 ->  state_Z2;            // No action
+     Z1 + event_1 ->  ,action_only;        // Empty state: do not change
+     Z1 + event_1 ->  action_only;  // No new state
+     // Note: In the last line Castle knows it only an action, as “action_only” is not a state!
+     // Potentially it conflict with the “redundancy rule”
+     Z1 + event_1 ->  None, action_only;        // None-state: do not change
+
+
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/3.Design/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/3.Design/index.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,14 @@
+===============
+Language Design
+===============
+
+Castle has to be designed. Not only the “compiler”, but also the language itself. And the **“CC” concept**, And ....
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :glob:
+
+   *
+
+

diff -r 79905a473ddb -r de487fa932d9 CCastle/3.Design/zz.todo.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/3.Design/zz.todo.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,18 @@
+TODO (Design)
+*************
+
+Tree as std data-structure
+==========================
+
+.. todo::
+
+   * .. seealso: :ref:`matching-statements`
+
+   * Allow (aside of trees), also non-cyclic graps?
+
+   * Allow (local) “links” in the tree
+
+     - ala html: a/href
+     - ala xlm: XLINK
+     - Use XPATH/CSS alike syntax
+     - Use ‘id’

diff -r 79905a473ddb -r de487fa932d9 CCastle/index.rst
--- a/CCastle/index.rst	Fri Jun 10 19:18:51 2022 +0200
+++ b/CCastle/index.rst	Sun Oct 02 14:51:50 2022 +0200
@@ -10,8 +10,8 @@
 
    --ALbert Mietus
 
-It’s also the first programming-language that support **CC**: Connected Components. Where `CC` is kind of of the
-successor of OO: active ‘things’ that communicate (solely) by input *and* output ports ...
+It’s also the first programming-language that support **CC**: Connected Components (or *Concurrent  Components*). Where
+`CC` is kind of of the successor of OO: active ‘things’ that communicate (solely) by input *and* output ports ...
 |BR|
 *(Yes, I know, ambition and reality are not always aligned...)*
 
@@ -32,7 +32,7 @@
 ‘One day’ the pages will be incorporated into the (docs of, the source of) `CCastle2 <https://osdn.net/users/albertmietus/pf/CCastle2>`_
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :titlesonly:
    :glob:
 
@@ -47,3 +47,11 @@
    **2017**). which has no theme and other support to make it more nice-looking. Therefore all those “lines” are comment
    out (or rewritten)
 
+
+Needs (index)
+==============
+
+.. needtable::
+   :style: table
+   :sort: title
+

diff -r 79905a473ddb -r de487fa932d9 Makefile
--- a/Makefile	Fri Jun 10 19:18:51 2022 +0200
+++ b/Makefile	Sun Oct 02 14:51:50 2022 +0200
@@ -52,4 +52,7 @@
 
 wc:
 	@echo "lines	words	file"
-	@wc -lw `find CCastle/ -iname \*rst`|sort -r
+	@wc -lw `find CCastle/ -iname \*rst`|sort -r | grep -v /index.rst | grep -v /zz.todo.rst
+
+sidebar:
+	@grep "include::" `find CCastle/ -type f -name \*.rst` /dev/null | grep sidebar| sort| sed 's/:../:\t\t ../'

diff -r 79905a473ddb -r de487fa932d9 _external_templates/static/SwBMnl+rtfd.css
--- a/_external_templates/static/SwBMnl+rtfd.css	Fri Jun 10 19:18:51 2022 +0200
+++ b/_external_templates/static/SwBMnl+rtfd.css	Sun Oct 02 14:51:50 2022 +0200
@@ -73,3 +73,26 @@
 .rst-content .localtoc.sidebar {
     max-width:40%; width: auto;
 }
+.rst-content h5,
+.rst-content h6 {
+    margin-bottom: 0;
+    color: #000066;
+}
+
+.rst-content a.external {
+    color: inherit;
+    border: 0.5px solid  #d6d6d6;
+    text-decoration: underline;
+    text-decoration-color: #d6d6d6;
+}
+.rst-content a.external:visited { color:inherit;}
+.rst-content a.external:hover   {
+    color:#000066;
+    text-decoration: underline;
+    text-decoration-color: #000066;
+}
+aside.sidebar  { line-height: inherit; }
+aside.sidebar .rubric {
+    margin-bottom: 0;
+    color: #000066;
+}

diff -r 79905a473ddb -r de487fa932d9 std/localtoc2.irst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/std/localtoc2.irst	Sun Oct 02 14:51:50 2022 +0200
@@ -0,0 +1,11 @@
+.. -*- rst -*-
+   USE AS:
+   .. include:: /std/localtoc2.irst
+
+.. sidebar:: On this page
+   :class: localtoc
+
+   .. contents::
+      :depth: 2
+      :local:
+      :backlinks: none