4.6.5.2 MPtcp links

MPtcp links give the possibility to exchange data in the binary MP format between two processes which may run on the same or on different computers. MPtcp links can be opened in four different modes:

listen

SINGULAR acts as a server.

connect

SINGULAR acts as a client.

launch

SINGULAR acts as a client, launching an application as server.

fork

SINGULAR acts as a client, forking another SINGULAR as server.

The MPtcp link describing string has to be

• listen mode:
  1. "MPtcp:listen --MPport " + portnumber

  SINGULAR becomes a server and waits at the port for a connect call.

• connect mode:
  1. "MPtcp:connect --MPport " + portnumber
  2. "MPtcp:connect --MPhost " + hostname + " --MPport " + portnumber

  SINGULAR becomes a client and connects to a server waiting at the host and port.

• launch mode:
  1. "MPtcp:launch"
  2. "MPtcp:launch --MPrsh " + rsh
  3. "MPtcp:launch --MPrsh " + rsh + " --MPhost " + hostname
  4. "MPtcp:launch --MPrsh " + rsh + " --MPhost " + hostname + " --MPapplication " + application

  SINGULAR becomes a client and starts (launches) the application using the specified remote shell command (default is ssh) on a (possibly) different host (default is localhost which then acts as a server.

• fork mode:
  1. "MPtcp:fork"

  SINGULAR becomes a client and forks another SINGULAR on the same host which acts as a server.

There are the following default values:

• if none of listen, connect, launch or fork is specified, the default mode is set to fork.
• if no remote shell (rsh) command is specified, then the command ssh is used.
• if no application is specified (in mode launch) the default application is the value of system("Singular") + "-bq". (This evaluates to the absolute path of the SINGULAR currently running with the option "-bq" appended.)
• if no hostname is specified the local host is used as default host.

To open an MPtcp link in launch mode, the application to launch must either be given with an absolute pathname, or must be in a directory contained in the search path. The launched application acts as a server, whereas the SINGULAR that actually opened the link acts as a client. SINGULAR automatically appends the command line arguments "--MPmode connect --MPhost hostname --MPport portnumber" to the command line of the server application. Both hostname and portnumber are substituted by the values from the link specification. The client "listens" at the given port until the server application does a connect call. If SINGULAR is used as server application it has to be started with the command line option -b. Since launching is done using a remote shell command, the host on which the application should run must have an entry in the .rhosts file. Even the local machine must have an entry if applications are to be launched locally.

If the MPtcp link is opened in fork mode a child of the current SINGULAR is forked. All variables and their values are inherited by the child. The child acts as a server whereas the SINGULAR that actually opened the link acts as a client.

To arrange the evaluation of an expression by a server, the expression must be quoted using the command quote (see quote), so that a local evaluation is prevented. Otherwise, the expression is evaluated first, and the result of the evaluation is written, instead of the expression which is to be evaluated.

If SINGULAR is in server mode, the value of the variable mp_ll is the MPtcp link connecting to the client and SINGULAR is in an infinite read-eval-write loop until the connection is closed from the client side (by closing its connecting link). Reading and writing is done to the link mp_ll: After an expression is read, it is evaluated and the result of the evaluation is written back. That is, for each expression which was written to the server, there is exactly one expression written back. This might be an "empty" expression, if the evaluation on the server side does not return a value.

MPtcp links should explicitly be opened before being used. MPtcp links are bidirectional, i.e., can be be used for both, writing and reading. Reading from an MPtcp link blocks until data was written to that link. The status command can be used to check whether there is data to read.

Example:

  LIB "general.lib"; // needed for "killall" command
  link l="MPtcp:launch";
  open(l); l;        // l is ready for writing but not for reading
→ // type : MPtcp
→ // mode : launch
→ // name : 
→ // open : yes
→ // read : not ready
→ // write: ready

  ring r; ideal i=x2+y,xyz+z,x2+y2;

  write (l,quote(std(eval(i))));   // std(i) is computed on server
  def j = read(l);j; // result of computation on server is read
→ j[1]=z
→ j[2]=y2-y
→ j[3]=x2+y2

  write(l, quote(getdump(mp_ll))); // server reads dump
  dump(l);           //  dump is written to server (includes proc's)
  read(l);           // result of previous write-command is read
  killall("not", "link"); killall("proc"); // kills everything, but links
→ // ** killing the basering for level 0

  write(l, quote(dump(mp_ll)));    // server writes dump
  getdump(l);        // dump is read from server
  read(l);           // result of previous write-command is read

  close(l);          // server is shut down
  listvar(all);      // same state as we had before "killall()"
→ // mpsr_r0              [0]  ring
→ // r                    [0]  *ring
→ //      j                    [0]  ideal, 3 generator(s)
→ //      i                    [0]  ideal, 3 generator(s)
→ // l                    [0]  link

  l = "MPtcp:";      // fork link declaration
  open(l); l;        // Notice that name is "parent"
→ // type : MPtcp
→ // mode : fork
→ // name : parent
→ // open : yes
→ // read : not ready
→ // write: ready

  write(l, quote(status(mp_ll, "name")));
  read(l);           // and name of forked link is "child"
→ child
  write(l,quote(i)); // Child inherited vars and their values
  read(l);
→ _[1]=x2+y
→ _[2]=xyz+z
→ _[3]=x2+y2
  close(l);          // shut down forked child