Base for the actor system (just some docs)

src/kernel/entry.lua

@@ -2,4 +2,6 @@
 -- this is responsible for initializing core kernel services
 -- required to advance to the next step of the OS
 
+require 'kernel.system'
+
 os.run({}, "/rom/programs/advanced/multishell.lua") -- placeholder

src/kernel/system.lua

@@ -0,0 +1,117 @@
+--[[
+    The Erica Actor System ([Er]lang + A[kka])
+
+    Each actor has:
+    - Coroutine
+    - Mailbox
+    - Address
+    - Extra Addresses
+    - State
+    - Child IDs
+
+    The Actor System utilizes coroutine yielding for all invocations of the system. No global APIs are exposed by the system.
+    The following calls are available to actors:
+    - spawn function:handler table?:options
+        The options table exposes the following:
+        - addressBase   | default: seedocs | If not provided, the address will take this form: "$currentAddress/$childId" and childId gets incremented
+                                           | in local state. 
+                                           | If provided, the global address base counter gets updated and the provided address base is used.
+                                           | Actors created without an address base are considered child actors of the current actor,
+                                           | and their status updates (death) will emit status update events to the next immediate parent.
+                                           | The death of an actor will kill all of it's children recursively.
+        - localNamespace| default: nil     | If set, adds the localNamespace into the address of the newly spawned actor.
+        - extraAddresses| default: {}   | Logic for global base addresses, that are used to add receive-only extra addresses to this actor.
+        The returned value is: bStatus, tAddress?
+        - bStatus: True if successful, false if failed
+        - tAddress: Address of newly spawned actor
+    
+    - tell addressPredicate:string ...content
+        Any instances of `?` in addressPredicate are replaced with a random valid instance.
+        Adds a message of "content" to the mailbox of the target actor
+        The returned value is: bStatus, sData?
+        - bStatus: True if successful, false if failed
+        - sData: The error string if status is false, for example no valid instances.
+                 If status is true, actor address that received this tell.
+    
+    - announce addressPredicate:string ...content
+        Any instances of `?` in addressPredicate are replaced with all valid instances.
+        Adds a message of "content" to the mailbox of the target actor
+        The returned value is: bStatus, data?
+        - bStatus: True if successful, false if failed
+        - data:  The error string if status is false, for example no valid instances.
+                 If status is true, amount of actors that received this announcement.
+    
+    - ask addressPredicate:string timeout:number ...content
+        Suspends this actor until the responseHandle is used with the "reply" or "fail" syscall,
+        or until the timeout elapses. The timeout elapsing invalidates the handle and makes calls to "reply" or "fail" fail silently.
+        The return value is:
+        - bStatus: If the ask was successful
+        - ...data: If the status is false, this contains the reason for the error.
+                   If the status is true, the first value is the actor asked, and subsequent data contains the response from the actor asked.
+    
+    - reply askHandle:string ...data
+        Replies to an ask. Returns nil.
+    
+    - fail askHandle:string ...reason
+        Fails an ask. Returns nil.
+
+    - idle timeout:number receiveUnfiltered?:bool
+        Notifies the actor system that this actor is ready to process events. Values returned by this call are described below, in the signals section.
+        If receiveUnfiltered is set, the actor will receive "hostEvent" signals without any filtering.
+
+    Signals:
+    - timeout
+        When the idle call times out. No extra params
+    - message sourceAddress:string {content}
+        When a message is received from another actor.
+    - ask replyHandle:string sourceAddress:string {content}
+        When an ask is received from another actor. Good idea to immediately fail any asks that the current actor doesn't recognize.
+    - childStatus address:string {newStatus}
+        When a child's status updates (coroutine.status() call)
+    - hostEvent {data}
+        ComputerCraft event from the top level coroutine.yield() call. Use with caution, generally this should only be used by actors
+        that propagate events to announcement channels.
+
+    Addresses
+    There are 3 types of address:
+    - Fully Qualified Address
+    - Local Address
+    - Relative Address
+
+    Fully Qualified addresses take on the following format:
+        systemId .. ":/" .. localAddressWithinSystem
+
+        The purpose of fully qualified addresses is to be provided by the system to actors to have unambigous resolution of actors.
+        User-written code generally shouldn't need to use fully qualified addresses, because their primary use case is future compatibility
+        with a version of this system that allows multi-node operation (and setting wildcards on systemId)
+    
+    Local Addresses are full addresses within a single system.
+        The "child:" prefix is reserved in address parts only for automatically-generated addresses, and manual usage of it in addresses
+        is considered undefined behavior.
+
+        Here is an example address of the first actor spawned within the "com/colon-three/someApp" namespace:
+            "com/colon-three/someApp/1"  (subsequent actors are 2, 3, 4, etc. Monotonically increasing, but not guaranteed. Do not rely on this.)
+        
+        If that actor then makes a child, that child's address is:
+            "com/colon-three/someApp/1/child:1"
+        
+        And if that child makes another child, that child's address is:
+            "com/colon-three/someApp/1/child:1/child:1"
+        
+        If that actor makes a child with the local namespace of "someNs", the address will be:
+            "com/colon-three/someApp/1/someNs/child:2" (because child:1 for this actor already exists, and namespaces are for filtering only.)
+        
+        Every address of an actual actor ends with either a plain number, or the "child:number" template.
+
+    Relative Addresses:
+        Used only in calls, and taking the following format:
+            ".." - refer to the parent actor. IGNORES NAMESPACES!!!
+            "../someNs" - refer to parent actor's "someNs". Ignores the current actor's namespace.
+            "./someNs" - refer to the current actor's someNs namespace.
+
+        Allows asking the parent something, or the parent broadcasting something to all of it's children, or children in a specific namespace.
+        This is generally only useful with `?` in asks or broadcasts, because a child's ID shouldn't be considered predictable.
+]]
+
+local tActors = {}
+local tAddressBases = {}