Using WSTP to Communicate between Wolfram System Sessions

WSTP connections between Wolfram System sessions.

This starts up a link on port number 8000:

link=LinkCreate["8000",LinkProtocol->"TCPIP"]

This connects to the link on port 8000:

Link=LinkConnect["8000",LinkProtocol->"TCPIP"]

This evaluates 15! and writes it to the link:

LinkWrite[link,15!]

This reads from the link, getting the 15! that was sent:

LinkRead[Link]

This writes data back on the link:

LinkWrite[Link,N[%^6]]

And this reads the data written in session B:

LinkRead[link]

One use of the Wolfram Symbolic Transfer Protocol (WSTP) connections between Wolfram System sessions is simply as a way to transfer data without using intermediate files.

Another use is as a way to dispatch different parts of a computation to different sessions.

This writes the expression 2+2 without evaluating it:

LinkWrite[link,Unevaluated[2+2]]

This reads the expression from the link, immediately wrapping it in (RefLink[Hold, paclet:ref/Hold]):

LinkRead[Link,Hold]

This evaluates the expression:

ReleaseHold[%]

If a link has been activated through completed previous calls to (RefLink[LinkWrite, paclet:ref/LinkWrite]), (RefLink[LinkRead, paclet:ref/LinkRead]), or (RefLink[LinkActivate, paclet:ref/LinkActivate]), expressions get written to a buffer, and if the whole expression fits in the buffer, (RefLink[LinkWrite, paclet:ref/LinkWrite]) immediately returns without need of a corresponding (RefLink[LinkRead, paclet:ref/LinkRead]). But when you call (RefLink[LinkRead, paclet:ref/LinkRead]), it will not return until it has read a complete expression from the WSTP connection.

You can tell whether anything is ready to be read by calling (RefLink[LinkReadyQ, paclet:ref/LinkReadyQ])[link]. If (RefLink[LinkReadyQ, paclet:ref/LinkReadyQ]) returns (RefLink[True, paclet:ref/True]), then you can safely call (RefLink[LinkRead, paclet:ref/LinkRead]) and expect immediately to start reading an expression. But if (RefLink[LinkReadyQ, paclet:ref/LinkReadyQ]) returns (RefLink[False, paclet:ref/False]), then (RefLink[LinkRead, paclet:ref/LinkRead]) will block until an expression for it to read has been written by a (RefLink[LinkWrite, paclet:ref/LinkWrite]) in your other Wolfram System session.

There is nothing waiting to be read on the link, so if (RefLink[LinkRead, paclet:ref/LinkRead]) were to be called, it would block:

LinkReadyQ[link]

This writes an expression to the link:

LinkWrite[Link,x+y]

Now there is an expression waiting to be read on the link:

LinkReadyQ[link]

(RefLink[LinkRead, paclet:ref/LinkRead]) can thus be called without fear of blocking:

LinkRead[link]

(RefLink[LinkReadyQ, paclet:ref/LinkReadyQ]) can take a list of link objects, evaluating each link in parallel to determine if there is data to read. As in the case of a single link, a second argument specifies a timeout period, causing (RefLink[LinkReadyQ, paclet:ref/LinkReadyQ]) to wait until one of the links is ready to use.

Ways to set up WSTP links over TCP/IP.

WSTP can use whatever mechanism for interprogram communication your computer system supports. In setting up connections between concurrent Wolfram System sessions, a common mechanism is internet TCP ports.

Most computer systems have a few thousand possible numbered ports, some of which are typically allocated to standard system services.

You can use any of the unallocated ports for WSTP connections.

This finds an unallocated port on frog.wolfram.com:

link=LinkCreate[LinkProtocol->"TCPIP"]

This connects to the port on frog.wolfram.com:

link=LinkConnect["2981@frog.wolfram.com,2982@frog.wolfram.com",LinkProtocol->"TCPIP"]

This sends the current machine name over the link:

LinkWrite[link,$MachineName]

This reads the expression written on toad:

LinkRead[link]

By using internet ports for WSTP connections, you can easily transfer data between Wolfram System sessions on different machines. All that is needed is that an internet connection exists between the machines.

Note that because WSTP is completely system independent, the computers at each end of a WSTP connection do not have to be of the same type. WSTP nevertheless notices when they are, and optimizes data transmission in this case.