Browse Source

Added some explanation of other services as well

Yentl Van Tendeloo 3 years ago
parent
commit
bb2955f6f2
1 changed files with 17 additions and 6 deletions
  1. 17 6
      doc/services.rst

+ 17 - 6
doc/services.rst

@@ -2,8 +2,8 @@ External Services
 =================
 
 Up to now, everything was contained in the Modelverse.
-Nonetheless, this is not always possible, or desired: sometimes we want to run an operation through an external tool, or a service.
-There are two main reasons why we would like this: performance, and feasability.
+Nonetheless, this is not always possible, or desired: sometimes we want to run an activity using an external tool, or a service.
+There are two main reasons why we would like this: performance and feasability.
 
 For performance, an external service is likely to be faster than a Modelverse-based implementation.
 Not only because the action language execution of the Modelverse is comparatively slow, but also because of the optimized implementation of the external tool.
@@ -16,11 +16,11 @@ This links back to performance, but also to the algorithms required for the oper
 For example, reimplementing a differential equation solver is wasteful, knowing that specialized tools have spent many man-years to implement and optimize it.
 We can never dream to come even close to these implementations.
 
-Both go hand-in-hand: a naive implementation is often possible, but there is always the trade-of between spending more time in developing the algorithm, and more time in using the algorithm.
+Both go hand-in-hand: a naive implementation is often possible, but there is always the tradeoff between spending more time in developing the algorithm, and more time in using the algorithm.
 The ideal solution would be to use an existing tool, thereby relying on the expertise of other developers, and merely making it available in the Modelverse.
 
 When making this available in the Modelverse, we strife to minimize the difference between an internal and external operation.
-This can be done using services: instead of modelling the operation, we model the communication with a tool that does the operation.
+This can be done using services: instead of modelling the activity, we model the communication with a tool that does the actual activity.
 While there remains a big difference, as we cannot alter the semantics of the external tool, we come fairly close, abstracting away from the tool that is actually used for the operation.
 
 In this section, we will illustrate this operation through the use of a *Fibonacci* service, which takes a single integer, and returns the Fibonacci number corresponding to it.
@@ -110,7 +110,7 @@ Both functions have the expected signature.
 The service function is invoked on a thread, and therefore runs concurrently with other invocations of this same service.
 Upon termination of the function, the thread ceases to exist.
 All threads are daemon threads, such that, if the service wants to exit, it can immediately exit without first finishing up the processing of tasks in the Modelverse.
-The Modelverse tasks should be resilient to service failure or termination anyway, possibly through the use of a statechart that contains timeouts.
+It is up to the Modelverse tasks to be resilient to such service failure or termination anyway, possibly through the use of a statechart that contains timeouts.
 
 When the service is registered, we have to specify the name of the service to be used in the Modelverse on a *comm_connect* call.
 The second parameter is the function to invoke when a connection is made, and must take one parameter: the communication port to be used.
@@ -173,7 +173,7 @@ Also, by using external services, it becomes possible to rely on trusted parsers
 
 Users of the *compile_code* and *compile_model* functions are never exposed to the use of an external service: it looks exactly like any other function call.
 Nonetheless, there is a small difference: when the external service encounters a problem, or is simply not running, the functions will not be able to operate, even though the input is correct.
-In any case, the compile_code and compile_model operations return the root element when they encounter a problem.
+In any case, the compile_code and compile_model operations return a string value if they encounter a problem.
 This problem could be anything, such as a syntax error or a semantical analysis error.
 Otherwise, the functions return the action language function and model, respectively.
 
@@ -183,3 +183,14 @@ Before you can execute these functions, the HUTN compilation service must be run
 
 The service will connect to the Modelverse specified in its configuration (i.e., the *init* call).
 It stays connected until the *STOP* input is given on *stdin*.
+
+Others
+------
+
+Many other services have been defined and are automatically ran by the Modelverse.
+This includes a JSON service (serialization and deserialization), a file server (persistent storage to files), a DEVS simulation server (both interactive and batch execution), and a PetriNet analysis service.
+
+New services can easily be defined by putting a Python file in the *services* folder of the Modelverse.
+All its subfolders are traversed and for each the *main.py* file is executed upon starting the Modelverse.
+Upon starting the Modelverse, a log is printed to stdout of which services have started up.
+When the Modelverse terminates, all services also quit.