Add short socket module documentation

doc/userdoc.org

@@ -4720,6 +4720,105 @@ This function just saves a ~mesh~ using a ~writer~. The ~gnuplot_1d_writer~
 cannot write mesh. And the ~writer~ argument must not be time series
 ~writer~.
 
+
+*** The ~socket~ module
+
+This module is more dedicated to developers that intend to drive ~pugs~
+or to couple it to other codes using sockets.
+
+We describe here language utilities that can be useful but effective
+coupling generally requires ~C++~ coding.
+
+Here is the list of the functions and types that the module provides.
+#+NAME: get-module-info-socket
+#+BEGIN_SRC pugs :exports both :results output
+  cout << getModuleInfo("socket") << "\n";
+#+END_SRC
+#+RESULTS: get-module-info-socket
+
+**** ~soket~ provided types
+
+***** ~socket~
+
+This is the ~socket~ descriptor type.
+
+This module adds the following binary operator
+| ~ostream <<~ allowed expression type |
+|------------------------------------|
+| ~socket~                             |
+
+For instance running the following code
+#+NAME: print-socket
+#+BEGIN_SRC pugs :exports both :results output
+  import socket;
+
+  let s:socket, s = createSocketServer(0);
+  cout << s << "\n";
+
+#+END_SRC
+gives
+#+RESULTS: print-socket
+The output uses the classical format: ~machine_nam:port_number~.
+
+**** ~socket~ provided functions
+
+***** socket management functions
+
+There are three socket management functions.
+
+****** ~createSocketServer: N -> socket~
+
+This function creates a socket server on the current machine. The
+integer parameter (of type ~N~) is the port number. If one uses the
+magical value $0$ a free port is assigned (this is the standard
+behavior for server socket creation). The return value is the ~socket~
+itself.
+
+****** ~connectSocketServer: string*N -> socket~
+
+Connects ~pugs~ to the server described by a name and a port number. It
+returns a socket to the server.
+
+****** ~acceptSocketClient: socket -> socket~
+
+Accepts connection from a client. The argument is the server socket
+and the return socket to the client.
+
+***** writing and reading basic types through sockets
+
+****** Writing functions
+
+These polymorcphic overload send a basic value through the given ~socket~
+- ~write: socket*B -> void~
+- ~write: socket*N -> void~
+- ~write: socket*Z -> void~
+- ~write: socket*R -> void~
+- ~write: socket*Rˆ1 -> void~
+- ~write: socket*Rˆ2 -> void~
+- ~write: socket*Rˆ3 -> void~
+- ~write: socket*Rˆ1x1 -> void~
+- ~write: socket*Rˆ2x2 -> void~
+- ~write: socket*Rˆ3x3 -> void~
+- ~write: socket*string -> void~
+
+****** Reading functions
+
+These are the reading counterparts of the previous functions. The
+argument is the ~socket~ on which values are read.
+
+- ~read_B: socket -> B~
+- ~read_N: socket -> N~
+- ~read_Z: socket -> Z~
+- ~read_R: socket -> R~
+- ~read_R1: socket -> Rˆ1~
+- ~read_R2: socket -> Rˆ2~
+- ~read_R3: socket -> Rˆ3~
+- ~read_R1x1: socket -> Rˆ1x1~
+- ~read_R2x2: socket -> Rˆ2x2~
+- ~read_R3x3: socket -> Rˆ3x3~
+- ~read_string: socket -> string~
+
+
 [fn:pugs-def] ~pugs~: Parallel Unstructured Grid Solvers
 [fn:MPI-def] ~MPI~: Message Passing Interface
 [fn:DSL-def] ~DSL~: Domain Specific Language