Updated documentation to incorporate socket2event code

doc/index.rst

@@ -24,10 +24,11 @@ Contents
     Runtime Platforms <runtime_platforms>
     Examples <examples>
     Semantic Options <semantic_options>
+    Socket Communication <sockets>
     Internal Documentation <internal_documentation>
     
 References
 ----------
     
 .. [SCCD] Simon Van Mierlo, Yentl Van Tendeloo, Bart Meyers, Joeri Exelmans, and Hans Vangheluwe. SCCD: SCXML extended with class diagrams. In *3rd Workshop on Engineering Interactive Systems with SCXML, part of EICS 2016*, 2016. [`LINK <http://www.scxmlworkshop.de/eics2016/submissions/SCCD%20SCXML%20Extended%20with%20Class%20Diagrams.pdf>`_]
-.. [Statecharts] David Harel. Statecharts: A visual formalism for complex systems. *Sci. Comput. Program. 8*, 3 (1987), 231–274. [`LINK <http://www.inf.ed.ac.uk/teaching/courses/seoc/2005_2006/resources/statecharts.pdf>`_]
+.. [Statecharts] David Harel. Statecharts: A visual formalism for complex systems. *Sci. Comput. Program. 8*, 3 (1987), 231–274. [`LINK <http://www.inf.ed.ac.uk/teaching/courses/seoc/2005_2006/resources/statecharts.pdf>`_]

doc/sockets.rst

@@ -0,0 +1,101 @@
+Socket Communication
+====================
+
+Sockets, for network communication, are an oftenly needed capability for many complex system.
+By default, however, Statecharts, and SCCD in particular, do not handle socket communication at all.
+Shifting all socket communication into action code is not an option either, as it is potentially a blocking operation.
+Additionally, the code wraps different socket implementations and socket configuration.
+
+This module will, after starting the translation service, translate all events on the *socket_in* and *socket_out* port to socket operations.
+Blocking then happens on another thread, while the statechart can continue its usual execution.
+When the socket operation returns, the result will be raised in the statechart as an event.
+
+Initialization
+--------------
+
+To use the translation service, several steps should be followed:
+
+    1. Import sccd.sccd_runtime.socket2event as socket2event;
+    2. Write your model with a *socket_in* and *socket_out* port;
+    3. Before starting the controller, invoke *socket2event.boot_translation_service(controller)* with the controller as its first argument;
+    4. Now raise and catch events as specified here, to communicate with sockets.
+
+Input Events
+------------
+
++-------------------+-----------------------------------+-------------------------------+
+| Event             | Parameters                        | Meaning                       |
++===================+===================================+===============================+
+| accept_socket     | socket                            | socket.accept()               |
++-------------------+-----------------------------------+-------------------------------+
+| recv_socket       | socket                            | socket.recv(2**16)            |
++-------------------+-----------------------------------+-------------------------------+
+| connect_socket    | socket, address                   | socket.connect(address)       |
++-------------------+-----------------------------------+-------------------------------+
+| create_socket     |                                   | new Socket()                  |
++-------------------+-----------------------------------+-------------------------------+
+| close_socket      | socket                            | socket.close()                |
++-------------------+-----------------------------------+-------------------------------+
+| send_socket       | socket, data                      | socket.send(data)             |
++-------------------+-----------------------------------+-------------------------------+
+| bind_socket       | socket, address                   | socket.bind(address)          |
++-------------------+-----------------------------------+-------------------------------+
+| listen_socket     | socket                            | socket.listen()               |
++-------------------+-----------------------------------+-------------------------------+
+| stop              | socket                            | stops translator service      |
++-------------------+-----------------------------------+-------------------------------+
+
+Output Events
+-------------
+
++-----------------------+-----------------------------------+-------------------------------+
+| Event                 | Arguments                         | Response to                   |
++=======================+===================================+===============================+
+| received_socket       | socket, data                      | recv_socket                   |
++-----------------------+-----------------------------------+-------------------------------+
+| sent_socket           | socket, bytes                     | send_socket                   |
++-----------------------+-----------------------------------+-------------------------------+
+| accepted_socket       | socket, connection                | accept_socket                 |
++-----------------------+-----------------------------------+-------------------------------+
+| connected_socket      | socket                            | connect_socket                |
++-----------------------+-----------------------------------+-------------------------------+
+| closed_socket         | socket                            | close_socket                  |
++-----------------------+-----------------------------------+-------------------------------+
+| bound_socket          | socket                            | bind_socket                   |
++-----------------------+-----------------------------------+-------------------------------+
+| listened_socket       | socket                            | listen_socket                 |
++-----------------------+-----------------------------------+-------------------------------+
+| error_socket          | socket, error                     | Socket error occurs           |
++-----------------------+-----------------------------------+-------------------------------+
+| unknown_error_socket  | socket, error                     | Python error occurs           |
++-----------------------+-----------------------------------+-------------------------------+
+
+HTTP client/server
+------------------
+
+Using this library, an HTTP echo client and server are implemented.
+The server echoes all data received from the client.
+The client connects to the server and sends some data.
+These are included in the examples directory
+
+Compile the server using::
+
+   python python_sccd_compiler/sccdc.py -p threads server.xml
+
+and the client using::
+
+   python python_sccd_compiler/sccdc.py -p threads client.xml
+
+Afterwards, you can run the server as::
+
+   python run_server.py
+
+which will start up a simple HTTP echo server on port 8080
+(configurable in constructor).
+Then you can start up several clients using::
+
+   python run_client.py
+
+The client will send out a counter to the server and print out the
+reply. The server is able to connect to multiple clients simultaneously,
+so can handle multiple open connections without getting confused.