Wolfram Language & System 11.0 (2016)|Legacy Documentation

This is documentation for an earlier version of the Wolfram Language.View current documentation (Version 11.2)

Using WSTP to Communicate between Wolfram System Sessions

LinkCreate["name"]create a link for another program to connect to
LinkConnect["name"]connect to a link created by another program
LinkClose[link]close a WSTP connection
LinkWrite[link,expr]write an expression to a WSTP connection
LinkRead[link]read an expression from a WSTP connection
LinkRead[link,Hold]read an expression and immediately wrap it with Hold
LinkReadyQ[link]find out whether there is data ready to be read from a link
LinkReadyQ[link,t]wait for up to t seconds to see if an expression becomes ready to read
LinkReadyQ[{link1,link2,}]find out whether there is data ready to be read from one of the links
LinkReadyQ[{link1,link2,},t]wait for up to t seconds to see if an expression becomes ready to read

WSTP connections between Wolfram System sessions.

Session A

This starts up a link on port number 8000.
Click for copyable input

Session B

This connects to the link on port 8000.
Click for copyable input

Session A

This evaluates 15! and writes it to the link.
Click for copyable input

Session B

This reads from the link, getting the 15! that was sent.
Click for copyable input
This writes data back on the link.
Click for copyable input

Session A

And this reads the data written in session B.
Click for copyable input

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.

Session A

This writes the expression 2+2 without evaluating it.
Click for copyable input

Session B

This reads the expression from the link, immediately wrapping it in Hold.
Click for copyable input
This evaluates the expression.
Click for copyable input

If a link has been activated through completed previous calls to LinkWrite, LinkRead, or LinkActivate, expressions get written to a buffer, and if the whole expression fits in the buffer, LinkWrite immediately returns without need of a corresponding LinkRead. But when you call 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 LinkReadyQ[link]. If LinkReadyQ returns True, then you can safely call LinkRead and expect immediately to start reading an expression. But if LinkReadyQ returns False, then LinkRead will block until an expression for it to read has been written by a LinkWrite in your other Wolfram System session.

Session A

There is nothing waiting to be read on the link, so if LinkRead were to be called, it would block.
Click for copyable input

Session B

This writes an expression to the link.
Click for copyable input

Session A

Now there is an expression waiting to be read on the link.
Click for copyable input
LinkRead can thus be called without fear of blocking.
Click for copyable input

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 LinkReadyQ to wait until one of the links is ready to use.

LinkCreate[LinkProtocol->"TCPIP"]pick any unused port on your computer
use a specific port
connect to a port on the same computer
connect to a port on another computer

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.

Session on frog.wolfram.com

This finds an unallocated port on frog.wolfram.com.
Click for copyable input

Session on toad.wolfram.com

This connects to the port on frog.wolfram.com.
Click for copyable input
This sends the current machine name over the link.
Click for copyable input

Session on frog.wolfram.com

This reads the expression written on toad.
Click for copyable input

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.