First info on interface and internals

doc/interface.rst

@@ -52,14 +52,14 @@ MvK server
 The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language.
 Requests have the following form::
 
-    op=OPERATION&username=USERNAME&value=VALUE
+    op=OPERATION&taskname=TASKNAME&value=VALUE
 
 Here, *OPERATION* defines the operation to execute, of which only two exist:
 
 1. *set_input*, which adds the sent value to the input queue of the user;
 2. *get_output*, which blocks until there is a value in the output queue of the user.
 
-Obviously, *USERNAME* specifies the name of the user for which the operation needs to happen.
+Obviously, *TASKNAME* specifies the name of the task for which the operation needs to happen.
 
 The *VALUE* is just a JSON encoded value which will be added to the input queue of the Modelverse.
 This is ignored when the *get_output* operation is used.
@@ -84,9 +84,9 @@ While this list mostly resembles JSON, there are some important differences:
 * Action type is new, and contains a string representation (without quotes!) of the action language construct to add
 
 As response, the *set_input* will always receive the same reply if the message was correctly deserialized.
-Receiving a reply does *NOT* mean that a message was consumed by the user, it only means that the message was correctly added to the input queue of that user.
+Receiving a reply does *NOT* mean that a message was consumed by the task, it only means that the message was correctly added to the input queue of that task.
 
-A *get_output* request blocks until a value is available in the users output queue.
+A *get_output* request blocks until a value is available in the tasks output queue.
 The reply to this message will then contain a JSON serialized (with identical remarks as for *set_input*) containing the value that was output.
 Note that now the *null* message is possible, in case the node that is being outputted does not contain a value (or is an edge).
 
@@ -94,5 +94,5 @@ Performance notes
 ^^^^^^^^^^^^^^^^^
 
 For performance reasons, sending a huge amount of data to the Modelverse (*e.g.*, a compiled program), should not happen with individual requests for each line.
-To allow for packed messages, users can ignore the *value* parameter, and use the *data* parameter instead.
+To allow for packed messages, tasks can ignore the *value* parameter, and use the *data* parameter instead.
 The content of this parameter should be a JSON encoded list of all individual values to be inserted.

doc/internal.rst

@@ -54,8 +54,13 @@ CE   create_edge
 CD   create_dict
 RV   read_value
 RE   read_edge
+RO   read_outgoing
+RI   read_incoming
 RD   read_dict
 RDN  read_dict_node
+RDE  read_dict_edge
+RDNE read_dict_node_edge
+RR   read_root
 DN   delete_node
 DE   delete_edge
 ==== ================
@@ -187,13 +192,14 @@ Primitives are functions implemented in the MvK core, and thus become hardcoded.
 
 To add a primitive, follow these steps:
 
-1. Add the code of the primitive to the MvK implementation by adding it in the file *primitives.py*.
+1. Add the code of the primitive to the MvK implementation by adding it in the file *kernel/modelverse_kernel/primitives.py*.
 
     a. Name the function identically to how the primitive will be invoked later on.
     b. Take a set of parameters. Parameters for primitives are always positional and start from *a* onwards.
     c. The final parameter should be a catch-all element, as it is possible that a high number of additional information is passed. In Python, this is done with a parameter prepended with \*\*.
-    d. When asking the MvS for information, use yields, just like the implementation of transformation rules in the MvK.
-    e. Instead of return, use a *raise* with the exception *PrimitiveFinished*. This exception takes one argument: the returnvalue.
+    d. The parameters are encoded using a dictionary notation, containing the keys *id* and *value*. The *value* key is the cached value of the node, or the value of a node that is still to be materialized.
+    e. When asking the MvS for information, use yields, just like the implementation of transformation rules in the MvK.
+    f. Instead of returning using Python code, yield a *RETURN* command, taking one argument: the returnvalue.
 
 2. Add the signature to *bootstrap.py* in the topmost dictionary *primitives*. The key is the name of the function, and the value is a list starting with the return type, followed by all parameter types (as string).
 3. Add the declaration to *includes/primitives.alh* to make them available everywhere.
@@ -205,7 +211,7 @@ To add a primitive, follow these steps:
 Adding a precompiled function
 -----------------------------
 
-Adding a precompiled function is way easier: only step 1 of the addition of a primitive should be done, but in the file *compiled.py* instead of *primitives.py*.
+Adding a precompiled function is way easier: only step 1 of the addition of a primitive should be done, but in the file *kernel/modelverse_kernel/compiled.py* instead of *kernel/modelverse_kernel/primitives.py*.
 All other steps are done automatically since there is an action language implementation present.
 The MvK will then automatically pick the precompiled function or the explicitly modelled operation, depending on preferences.
 A restart of the MvK is needed for Python to pick up the new functions.