It is a rather often occuring constellation that polymake script must simultaneously communicate with several processes running in parallel. These can be clients, external programs like nauty or TOPCOM, or interactive visualizers like JavaView. Without special precautions the parallel communication inavoidably leads to mutual blocking (deadlocks).
There is a family of related classes helping to solve this kind of problems. The base class is Poly::Pipe. It should used as a wrapper around all I/O handles connected to external processes:
The Poly::Pipe constructor takes an I/O handle or a reference to a handle and ties a special object to it. Then all reading and writing operations on the handle are protected against unexpected blocking.
In the most of cases you won't use this class directly, but one of its derivatives.
Filters are programs reading from stdin and writing to stdout, like the standard UNIX sort. The class Poly::ProgramPipe must be used to communicate with them:
Launches the program. Initially the object $p is in output mode. After the whole output has been sent to the program, the first reading operation toggles it to the input mode:
Note that the external program is expected to set the correct exit code, namely 0 for success. Any nonzero exit code will raise an exception when closing the pipe.
Interactive programs require asynchronous communication; both sides (polymake and the external program) can act as initiators of the data interchage. The best suited communication mechanism for these is an old good TCP socket. There are wrapper classes for both client and server side sockets.
A wrapper for the server side socket. It can either be bound to a fixed port number or choose a free port by itself, in both cases at the local loopback IP address 127.0.0.1. $p returned by accept is a Poly::Pipe object.
A wrapper for the client side socket.
Although clients are from the logical point of view nothing else as special subroutines for polymake script, technically they are still separate executables running in parallel processes. Since the client programs are using their own communication protocol, they must be started via special function client, but never with system:
Each command line argument must be passed as a separate expression, even the option keywords and values like -seed 1 must not be glued together. There are special rules about the client arguments:
The client must terminate with exit code 0 (success), otherwise an exception is raised.
The objects created by clients are not automatically saved after the session end unless you take care of this. If you want to store an object in a file, you must either do it explicitly:
or assign a name to the object during the creation:
Note the obligatory call to the commit method in both cases.