Introduction to WSTPServer
| Launching WSTPServer | Command Language |
| Persistent Kernels | Wolfram Language Functions |
| Kernel Pools | Appendix: Command-Line Options |
| Use with Various Clients | Appendix: Example Scenarios |
| Configuration File |
WSTPServer is a server program that launches and maintains Wolfram Language kernels for incoming WSTP connections. It listens on a single WSTP endpoint, allowing any number of clients to connect to a known location to obtain a kernel.
It routes all traffic to kernels that it manages, allowing links to WSTPServer to behave as if they were direct links to kernels. Kernels can be configured with specific properties through the use of kernel pools. Because a WSTPServer kernel can be connected to, disconnected from and reconnected to, you can maintain a long-lived session that you can connect to from different programs or machines. At the simplest level, you can think of WSTPServer as a provider of pre-launched, pre-configured Wolfram Language kernels, replacing the more typical procedure of launching a fresh kernel at the moment it is needed.
WSTPServer is a server program, and it must be running for you to be able to connect to it.
$ /Applications/Mathematica.app/Contents/SystemFiles/Links/WSTPServer/wstpserver
WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
Using "/Applications/Mathematica.app/Contents/MacOS/WolframKernel" as a default kernel path
WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
Listening for new connections on port 31415
...
$ "C:\Program Files\Wolfram Research\Mathematica\12.2\SystemFiles\Links\WSTPServer\wstpserver.exe"
WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
Using "C:\Program Files\Wolfram Research\Mathematica\12.2\wolfram.exe" as a default kernel path
WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
Listening for new connections on port 31415
...
On Linux, run the following in your terminal to launch WSTPServer:
$ /usr/local/Wolfram/Mathematica/12.2/SystemFiles/Links/WSTPServer/wstpserver
WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
Using "/usr/local/Wolfram/Mathematica/12.2/Executables/WolframKernel" as a default kernel path
WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
Listening for new connections on port 31415
...
Regarding the preceding, note that only 12.2 or later Wolfram Language layouts contain wstpserver. Adjust the paths accordingly if your product is not Mathematica (e.g. if it is Wolfram Desktop).
If your terminal returns to the command line, WSTPServer has exited due to an issue it cannot recover from, and you will not be able to connect to it. WSTPServer will log to your terminal the reason it exited.
WSTPServer can also be run under service management systems, such as launchd, systemd or the Windows Services Manager.
Wolfram Language kernels are usually limited by their connection to the user: when a connection dies, so does the associated kernel, stopping any work it was doing. However, WSTPServer allows the user to disconnect from a kernel without killing it or stopping its work and to reconnect later to the same kernel.
An advantage to connecting to a kernel through WSTPServer is that you can build up state (e.g. by loading files, making definitions and evaluating expressions) but then leave the kernel alive such that you can reconnect to it later on, even from a different machine. An example is given in the section "Bridging to a Previously Used Kernel."
Another advantage is that WSTPServer can prevent the deaths of kernels involved in interrupted network connections, allowing the work of the kernels to continue. Connections over networks can be fragile, and occasionally they cannot be maintained. To return to a lost kernel, all the user has to do is reconnect to the WSTPServer and direct it to connect to the kernel that was lost.
A final example pertains to a long-running computation. The user can begin a long-running computation in a kernel managed by WSTPServer and then return to the kernel when the computation is expected to be finished, obtaining the result. The user could also connect to other kernels managed by WSTPServer while the initial kernel is busy, providing them with tasks as well.
Every kernel has a corresponding kernel ID that can be used to connect to that kernel. These IDs can be obtained by evaluating WSTPServer`GetKernelID[] in the kernel or using the GetKernelID WSTP command.
The term "bridge" is used often in this document. WSTPServer acts like a middleman, forwarding communications back and forth between a client and a kernel. A bridge is the connection established by WSTPServer between a client and a kernel. "Unbridging" discontinues the connection between a client and a kernel, although a client can then be bridged to a different kernel.
For more information on connecting to specific kernels, see the descriptions of the Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel.
Kernel pools are groups of kernels that share a set of user-configured properties, such as initialization code. Most kernels managed by WSTPServer are expected to be members of such pools, and at least one kernel pool must be set as the default pool. Kernels from the default pool are provided to connections that do not request a specific kernel or pool. Configuring multiple kernel pools allows you to have different sets of pre-initialized kernels for different kinds of uses.
For more information on the configuration process for the default pool and kernel pools in general, see the section "Configuration File". For more information on connecting to specific kernels, see the descriptions of the Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel. An example is given in the section "Bridging to a Specially Configured Pool" that describes the use of WSTPServer`ConnectKernel in bridging to a specific kernel pool.
Much of the Wolfram System makes use of WSTP for communication with kernels. Accordingly, WSTPServer is easily integrated with many Wolfram System components.
This section gives a detailed description on the use of WSTPServer with many commonly used components.
Use with WolframScript
WolframScript is a command-line script interpreter for the Wolfram Language that can run Wolfram Language code, functions and deployed APIs. WolframScript can also connect to WSTPServer and interact with its kernels.
$ wolframscript -wstpserver -code "StringReverse[\"hello\"]"
olleh
WolframScript allows for the convenient reconnection to WSTPServer kernels. In order to accomplish this safely, it is recommended that connections to specific kernels be tracked in profiles on the filesystem that the user must manage. WolframScript records in the profile file the ID of the kernel being used in order to allow reconnection to that kernel.
You can also use -wstpserver to connect to a particular WSTPServer. In this example, we connect to the WSTPServer running on our local machine listening on the port 31416.
When using WolframScript without WSTPServer, you get a fresh kernel for every computation. Using WSTPServer with -startprofile and -continueprofile allows you to maintain a session with the same kernel across multiple WolframScript computations.
The section "DETAILS" of the program page "WolframScript" describes the profile system in greater detail, as well as the options -wstpserver, -startprofile and -continueprofile. The section "OPTIONS" provides a useful high-level overview of WolframScript's command-line options.
Use with the Notebook Interface
The following instructions describe how to connect the notebook front end to WSTPServer and how to interact with its kernels:
1. Start the front end on your local machine. On the toolbar, navigate to Evaluation ▶ Kernel Configuration Options....
2. Add a new kernel and configure it. In the dialog, click Add, and a Kernel Configuration dialog appears.
4. Select the Advanced Options switch. In the text field called "Arguments to MLOpen," enter the following, where "port" and "host" (optional) should be replaced by the port and host, respectively, that WSTPServer is listening on:
6. On the toolbar, navigate to Evaluation ▶ Notebook's Kernel and choose the name of the kernel that you just created.
7. Inside the notebook, verify that evaluating commands (e.g. 2+2, WSTPServer`GetKernelID[]) in the kernel managed by WSTPServer yields the expected results.
Some examples relating to the use of the notebook interface with WSTPServer are given in the section "Appendix: Example Scenarios."
Use for Parallel Computing
The Wolfram Language provides a powerful and unique environment for parallel computing. Typically, much of the functionality can be used with a minimum of effort and without paying too much attention to the low-level internals of the parallel system.
WSTPServer can manage a pool of parallel kernels for use by the parallel computing functionality. The parallel computing functionality requires additional configuration in order to connect to the WSTPServer parallel kernels. An example is given in the section "Making Use of the Parallel Computing Functionality" that describes this process when using the front end.
The WSTPServer-related section of "Types of Kernels to Configure" describes the interface with the parallel computing functionality in greater detail.
Use with the WSTP C Binding
All of the preceding clients make use of WSTP to a great extent, but they hide many of its lower-level details. WSTP provides a C binding for developers who want to use the full power of WSTP directly.
It is easy to connect to WSTPServer from your own WSTP programs. WSTP connections to WSTPServer are almost identical to connections to normal kernels. Typically, WSTPServer will send an InputNamePacket to the client when the client connects. WSTPServer will then forward any communications from the client to the kernel, and any communications from the kernel to the client. From the client's perspective, it appears to be a direct link to the kernel.
A significant exception to this description is that WSTPServer allows a class of commands to be sent over the WSTP connection in WSCommandPacket packets. These commands are intercepted by WSTPServer and are not forwarded to the kernel. Descriptions of these commands are given in the section "Command Language."
The following sample program connects to WSTPServer and performs a computation. It is a completely standard WSTP program except for the way in which the link is opened. Note the "-linkmode connect -linkname 31415 -linkprotocol TCPIP -linkoptions 4" specification in the call to WSOpenString.
/************************************
include directives
*************************************/
#include "stdio.h" /* printf */
#include "wstp.h" /* WSENV, WSLINK, WSInitialize, WSOpenArgcArgv, ... */
/************************************
define directives
*************************************/
#define WSTP_ENVIRONMENT_ERROR 1
#define WSTP_OPEN_ERROR 2
#define WSTP_ACTIVATION_ERROR 3
#define WSTP_INPUTNAMEPACKET_ERROR 4
#define WSTP_GENERAL_ERROR 5
/************************************
connecting to a link server
*************************************/
/* entry point */
int main(int argc, char **argv)
{
WSENV env;
WSLINK link;
int error;
/* initialize a WSTP environment */
env = WSInitialize(NULL);
if(env == NULL)
{
(void) printf("%s\n", "Could not initialize a WSTP environment");
return WSTP_ENVIRONMENT_ERROR;
}
/* open a link to a WSTPServer listening on port 31415 on the local machine */
link = WSOpenString(env, "-linkmode connect -linkname 31415 -linkprotocol TCPIP -linkoptions 4", &error);
if(link == NULL || error)
{
(void) printf("%s\n", "Could not open a link to WSTPServer");
return WSTP_OPEN_ERROR;
}
/* activate the link to WSTPServer */
error = WSActivate(link);
if(!error)
{
(void) printf("%s\n", "Could not activate the link to WSTPServer");
return WSTP_ACTIVATION_ERROR;
}
/* receive InputNamePacket packet */
if(WSNextPacket(link) != INPUTNAMEPKT)
{
(void) printf("%s\n", "Could not receive InputNamePacket packet");
return WSTP_INPUTNAMEPACKET_ERROR;
}
(void) WSNewPacket(link);
/* send over the link:
EvaluatePacket[2 + 2] */
if(
!(
WSPutFunction(link, "EvaluatePacket", 1) &&
WSPutFunction(link, "Plus", 2) &&
WSPutInteger(link, 2) &&
WSPutInteger(link, 2) &&
WSFlush(link)
)
)
{
(void) printf("%s\n", "General WSTP error occurred");
return WSTP_GENERAL_ERROR;
}
/* read off packets until ReturnPacket */
while(
(WSNextPacket(link) != RETURNPKT) &&
(WSError(link) == WSEOK)
) { }
if(WSError(link) != WSEOK)
{
(void) printf("%s\n", "General WSTP error occurred");
return WSTP_GENERAL_ERROR;
}
/* clean up */
(void) WSClose(link);
(void) WSDeinitialize(env);
return 0;
}
Configuration files are searched for first in the current working directory and then in the application data directory. If no valid configuration file is present, a configuration file with default content is created in the application data directory.
{
# Lines that begin with # are comments
# "AllowStealingKernels":false,
# "AllowSilentKernelReplacement":false,
# "EnableAutomaticKernelConnection":false,
# "SendInputNamePacketUponKernelConnection":true,
"Pools":
{
"KernelPoolOne":
{
# "Default":true,
# Only uncomment one of the "KernelPath" lines below
# Make sure to change the value to reflect the actual location of your Wolfram kernel binary
# "KernelPath":"C:\\Program Files\\Wolfram Research\\Mathematica\\13.2\\wolfram",
# "KernelPath":"/usr/local/Wolfram/Mathematica/13.2/Executables/WolframKernel",
# "KernelPath":"/Applications/Mathematica.app/Contents/MacOS/WolframKernel",
# "InitializationCode":"x=2+2",
# "InitializationFile":"/path/to/your/initialization/file.wl",
# "KernelOptions":"-yourkerneloption1 -yourkerneloption2",
# "KeepAlive":true,
# "MinimumKernelNumber":2,
# "ParallelKernels":false,
# "ReservePreviouslyConnectedKernels":false
},
# "KernelPoolTwo":
# {
# "ParallelKernelDefault":true,
# "ParallelKernels":true,
# Only uncomment one of the "KernelPath" lines below
# Make sure to change the value to reflect the actual location of your Wolfram kernel binary
# "KernelPath":"C:\\Program Files\\Wolfram Research\\Mathematica\\13.2\\wolfram",
# "KernelPath":"/usr/local/Wolfram/Mathematica/13.2/Executables/WolframKernel",
# "KernelPath":"/Applications/Mathematica.app/Contents/MacOS/WolframKernel"
# }
}
}
Key-Value Pairs
WSTPServer recognizes the following root keys in the configuration file:
AllowStealingKernels |
true
| whether a client can use a kernel ID to bridge to a kernel already bridged to another client | |
AllowSilentKernelReplacement |
false
| whether when a bridged kernel dies, a new kernel should be silently started to replace the dead kernel without closing the client link | |
EnableAutomaticKernelConnection |
false
| whether a kernel from the default pool should be bridged immediately with a client link upon connection, as opposed to bridging a kernel only when the first non-WSCommandPacket expression is sent over the client link | |
Pools | required | list of pools for WSTPServer to use | |
SendInputNamePacketUponKernelConnection |
true
| whether an InputNamePacket should be sent for bridging events that occur after the client connects |
At least one named kernel pool is required in Pools, but the key-value pairs it can contain are optional, and they have default values.
With AllowStealingKernels set to true, you can switch from one computer to another and keep the same kernel session without first unbridging from the kernel on the original computer.
With AllowSilentKernelReplacement set to true, kernels that WSTPServer itself closed (e.g. because of a KeepAlive flag set to false) will not be replaced. If AllowSilentKernelReplacement is false, when a bridged kernel dies, the client link bridged to the kernel will be closed.
If EnableAutomaticKernelConnection is true, a kernel will be bridged immediately with a client link when it is established. This can reduce the time the first evaluation using the client link takes because the kernel will be ready in advance of when it is needed.
Default | automatic | whether to use this pool as the default for new clients | |
InitializationCode | "" | initialization code to run for the kernels in the pool | |
InitializationFile |
""
| initialization file to run for the kernels in the pool | |
KernelPath | automatic | path to the Wolfram Language kernel executable that the kernels in the pool will run | |
KernelOptions | "" | additional command-line options to the Wolfram Language kernel executable that the kernels in the pool will run | |
KeepAlive |
true
| whether to keep kernels alive indefinitely or to close them when they become unbridged | |
MaximumKernelNumber | automatic | the maximum number of running kernels the pool can contain | |
MinimumKernelNumber |
2
| the minimum number of running kernels the pool will always contain | |
ParallelKernelDefault | automatic | whether to use this pool as the default for parallel computing | |
ParallelKernels |
false
| whether the kernels of the pool should be configured for parallel computing | |
ReservePreviouslyConnectedKernels | true | whether previously bridged kernels can only be bridged again with clients that request them by their IDs |
The automatic value for ParallelKernelDefault is true for the first pool object with ParallelKernels set to true.
The automatic value for KernelPath is an auto-discovered string, but this auto-discovery may fail; if so, KernelPath becomes required.
The automatic value for MaximumKernelNumber is the value of MinimumKernelNumber if this value is greater than 0; otherwise, the value is 2.
WSTPServer will pre-launch a number of kernels equivalent to the value of MinimumKernelNumber when it starts up. These kernels can be warmed up with the configuration file keys InitializationCode or InitializationFile.
With KeepAlive set to true, kernels will not be closed when a client disconnects, allowing them to be connected to again by the same client or a different client. Clients must be careful to use the Wolfram Language function WSTPServer`DisconnectKernel or the WSTP command DisconnectKernel instead of Quit or Exit, which will cause the kernel to exit.
If ReservePreviouslyConnectedKernels is false, preference is given to previously bridged kernels, if they exist, in order of when they were unbridged.
WSTPServer can be controlled dynamically through the use of commands. Commands are sent directly over a WSTP connection to WSTPServer in a special wrapper called WSCommandPacket; results of these commands are sent back in ReturnPacket packets. WSCommandPacket functionality is intended for developers writing their own WSTP programs for use with WSTPServer. A WSCommandPacket example is given in the section "Use with the WSTP C Binding."
ReturnPacket["{\"status\":\"PacketMalformed\"}"] will be returned if the command packet sent was not correctly structured.
CloseKernel | close the specified kernel | |
ConnectKernel | bridge the current connection with the specified kernel | |
ConnectParallelKernel | bridge the current connection with the first available kernel in the parallel kernel default pool | |
DisconnectKernel | unbridge the current connection with its bridged kernel | |
GetKernelBusyStatus | tell whether the kernel bridged to the current connection is busy with an evaluation | |
GetKernelID | get the ID of the kernel bridged to the current connection | |
GetNumberOfAvailableParallelKernels | get the number of available kernels in the parallel kernel default pool | |
GetPoolName | get the name of the pool of the kernel bridged to the current connection | |
GetServerInformation | get information about all pools and all kernels | |
SetAllowSilentKernelReplacement | set whether to allow or disallow the silent replacement of the kernel bridged to the current connection if that kernel dies | |
SetKeepAlive | set whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends | |
SetReserveKernel | set whether the current kernel, when unbridged, can only be bridged to clients that request it by ID | |
StartKernel | start a kernel (outside of any pools), and return its ID |
The following subsections describe all of the WSTP commands given in further detail.
WSTP Command: CloseKernel
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: ConnectKernel
WSCommandPacket[ConnectKernel[]] bridges the current connection with an available kernel from the default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectKernel["kernelSpecifier"]] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectKernel["kernelSpecifier", timeout]] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: ConnectParallelKernel
WSCommandPacket[ConnectParallelKernel[]] bridges the current connection with an available kernel from the parallel kernel default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectParallelKernel[timeout]] bridges the current connection with an available kernel from the parallel kernel default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: DisconnectKernel
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: GetKernelBusyStatus
WSCommandPacket[GetKernelBusyStatus[]] tells whether the kernel bridged to the current connection is busy with an evaluation. This function will fail if the current connection is not bridged.
WSCommandPacket[GetKernelBusyStatus["id"]] tells whether the kernel with the ID id is busy with an evaluation.
On success, ReturnPacket["{\"result\":\"True\"}"] or ReturnPacket["{\"result\":\"False\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: GetKernelID
On success, ReturnPacket["{\"result\":\"id\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: GetNumberOfAvailableParallelKernels
WSCommandPacket[GetNumberOfAvailableParallelKernels[]] gets the number of available kernels in the parallel kernel default pool.
On success, ReturnPacket["{\"result\":\"num\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned. The value of num is the number of available kernels in the parallel kernel default pool.
WSTP Command: GetPoolName
WSCommandPacket[GetPoolName[]] gets the name of the pool of the kernel bridged to the current connection.
On success, ReturnPacket["{\"result\":\"name\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: GetServerInformation
On success, ReturnPacket["json"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned. On success, json will match the JSON schema following:
{
"result":
{
# An object containing configured pools and their properties
"Pools":
{
string: # The name of a particular pool
# An object containing the properties of a particular pool and their values
{
"InitializationCode":string,
"InitializationFile":string,
"MaximumKernelNumber":number,
"MinimumKernelNumber":number,
"KeepAlive":Boolean,
"EntryPool":Boolean,
"KernelPath":string,
"PreferFreshKernel":Boolean,
"ReservePreviouslyConnectedKernels":Boolean,
"ParallelKernels":Boolean,
"ParallelKernelEntryPool":Boolean
},
...
}
}
}
}
An example is given in the section "Monitoring WSTPServer" that describes the use of the similar Wolfram Language function WSTPServer`GetServerInformation in monitoring WSTPServer.
WSTP Command: SetAllowSilentKernelReplacement
WSCommandPacket[SetAllowSilentKernelReplacement[setting]] allows or disallows the silent restart of the kernel bridged to the current connection if the kernel dies. The value of setting should be either True or False.
SetAllowSilentKernelReplacement fails if the current connection is not bridged. SetAllowSilentKernelReplacement overrides the AllowSilentKernelReplacement configuration file key with respect to the current bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: SetKeepAlive
WSCommandPacket[SetKeepAlive[setting]] instructs WSTPServer whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends. The value of setting should be either True or False.
SetKeepAlive fails if the current connection is not bridged. SetKeepAlive overrides the KeepAlive configuration file key with respect to the current bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: SetReserveKernel
WSCommandPacket[SetReserveKernel[setting]] sets whether the current kernel, when unbridged, can only be bridged to clients that request it by ID. The value of setting should be either True or False.
SetReserveKernel fails if the current connection is not bridged or if the kernel is not part of a pool. The effect of SetReserveKernel on the kernel persists through bridge events. SetReserveKernel overrides the ReservePreviouslyConnectedKernels configuration file key with respect to a bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
WSTP Command: StartKernel
WSCommandPacket[StartKernel["commandLine"]] starts a kernel (outside of any pools) with commandLine and returns its ID.
On success, ReturnPacket["{\"result\":\"id\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
The previous section described a low-level method to control WSTPServer using WSCommandPacket packets. There is also an analogous set of Wolfram Language functions that allows WSTPServer kernels themselves to access and control WSTPServer.
WSTPServer`CloseKernel | close the specified kernel | |
WSTPServer`ConnectKernel | bridge the current connection with the specified kernel | |
WSTPServer`DisconnectKernel | unbridge the current connection with its bridged kernel | |
WSTPServer`GetKernelID | get the ID of the kernel bridged to the current connection | |
WSTPServer`GetPoolName | get the name of the pool of the kernel bridged to the current connection | |
WSTPServer`GetServerInformation | get information about all pools and all kernels | |
WSTPServer`SetAllowSilentKernelReplacement | set whether to allow or disallow the silent replacement of the kernel bridged to the current connection if that kernel dies | |
WSTPServer`SetKeepAlive | set whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends | |
WSTPServer`SetReserveKernel | set whether the current kernel, when unbridged, can only be bridged to clients that request it by ID | |
WSTPServer`StartKernel | start a kernel (outside of any pools) and return its ID |
Wolfram Language Function: WSTPServer`CloseKernel
Wolfram Language Function: WSTPServer`ConnectKernel
WSTPServer`ConnectKernel[] bridges the current connection with an available kernel from the default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSTPServer`ConnectKernel["kernelSpecifier"] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSTPServer`ConnectKernel["kernelSpecifier", timeout] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
Wolfram Language Function: WSTPServer`DisconnectKernel
Wolfram Language Function: WSTPServer`GetKernelID
Wolfram Language Function: WSTPServer`GetPoolName
WSTPServer`GetPoolName fails if the current connection is not bridged, or if the kernel is not part of a pool.
Wolfram Language Function: WSTPServer`GetServerInformation
On success, an Association similar to the JSON schema given in the section "Monitoring WSTPServer" is returned; on failure, a failure object is returned.
An example is given in the section "Monitoring WSTPServer" that describes the use of the similar Wolfram Language function WSTPServer`GetServerInformation in monitoring WSTPServer.
Wolfram Language Function: WSTPServer`SetAllowSilentKernelReplacement
WSTPServer`SetAllowSilentKernelReplacement[setting] allows or disallows the silent restart of the kernel bridged to the current connection if the kernel dies. The value of setting should be either True or False.
WSTPServer`SetAllowSilentKernelReplacement fails if the current connection is not bridged. WSTPServer`SetAllowSilentKernelReplacement overrides the AllowSilentKernelReplacement configuration file key with respect to the current bridge.
Wolfram Language Function: WSTPServer`SetKeepAlive
WSTPServer`SetKeepAlive[setting] sets whether the current kernel, when unbridged, can only be bridged to clients that request it by ID. The value of setting should be either True or False.
WSTPServer`SetKeepAlive fails if the current connection is not bridged or if the kernel is not part of a pool. The effect of WSTPServer`SetKeepAlive on the kernel persists through bridge events. WSTPServer`SetKeepAlive overrides the KeepAlive configuration file key with respect to a bridge.
Wolfram Language Function: WSTPServer`SetReserveKernel
WSTPServer`SetReserveKernel[setting] sets, following the Boolean value setting, whether the current kernel, when unbridged, can only be bridged to clients that request it by ID.
WSTPServer`SetReserveKernel fails if the current connection is not bridged or if the kernel bridged to the current connection is not part of a pool. The effect of WSTPServer`SetReserveKernel on the kernel persists through future bridge events. WSTPServer`SetReserveKernel overrides the ReservePreviouslyConnectedKernels key from the configuration file for a kernel.
Wolfram Language Function: WSTPServer`StartKernel
WSTPServer`StartKernel["commandLine"] starts a kernel (outside of any pools) with commandLine and returns its ID.
The command-line options for WSTPServer are the following:
-h, --help | print help text | |
-l, --log-level n | specify the level of verbosity of messages | |
-f, --log-file [file] |
write messages to a specified file
| |
-a, --advertise [service] |
if present, advertise the link server as the specified service
| |
-p, --port port | listen on the specified port | |
-i, --interface interface | listen on the specified interface | |
-c, --configuration-file file | use the specificied configuration file |
error, 1 | report server startup/shutdown errors and print a successful startup message | |
debug, 2 | report everything from level 1 and all debug messages | |
trace, 3 | report everything from level 2 and all handled WSTP traffic |
If --log-file or -f is not used, or is used without specifying a file, messages will be written to stdout.
If
--advertise [service]
or -a [service]
is used, WSTPServer will try to advertise itself as WSTPServer-Instance
or WSTPServer-Instance-service
, depending on whether service was specified. WSTPServer will log the service name it is advertising at.If --interface or -i is not used, the link server will listen on the default network interface. Set the interface to localhost to make WSTPServer not visible on the local network.
If --configuration-file or -c is not used, the link server will use the default configuration file search behavior and usage.
Making Use of Parallel Computing Functionality
WSTPServer can manage a pool of parallel kernels for use by the Wolfram Language parallel computing functionality.
The following instructions demonstrate how to make use of parallel computing functionality with WSTPServer using the front end:
# wstpserver.conf: place in the current working directory
{
"Pools":
{
"IProvideParallelKernels":
{
"Parallel":true,
"MinimumKernelNumber":4
}
}
}
3. Add WSTPServer parallel kernels to the parallel computing functionality with AppendToConfiguredKernels["port@hostname", num]. The first argument describes the port and hostname (optional) of the WSTPServer to connect to. The second argument describes the number of WSTPServer parallel kernels to make use of.
4. Run some code that can make use of the parallel computing functionality (e.g. ParallelSum[EulerPhi[i], {i, 10^6}]).
5. Optionally, check that the configured WSTPServer parallel kernels were successfully connected to in step 3 with Kernels[].
Bridging to a Specially Configured Pool
WSTPServer allows for the configuration of pools for specific purposes (e.g. through the use of a shared initialization file). Use of the command language will be required to make use of such a pool if it is not the default pool. The Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel can be used to bridge to the pool.
The following instructions demonstrate how to bridge to a specially configured pool using WolframScript:
# wstpserver.conf: place in the current working directory
{
"Pools":
{
"IDefineX":
{
"InitializationCode":"x=4"
}
}
}
2. Using the console, run wolframscript -wstpserver -startprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
3. Inside the WolframScript REPL, optionally verify the pool of the currently bridged kernel with WSTPServer`GetPoolName[]. Note that x evaluates to 4 as expected given the initialization code for the pool.
$ wolframscript -wstpserver -kernelpool AlternativeThree
In[1]:= WSTPServer`GetPoolName[]
Out[1]= IDefineX
In[2]:= x
Out[2]= 4
In[3]:=
Bridging to a Previously Used Kernel
It can be useful to return to a previously used kernel after building up state. Typically this will require WSTPServer to be configured to keep kernels alive indefinitely using the configuration file key KeepAlive. The Wolfram Language function WSTPServer`ConnectKernel or the WSTP command ConnectKernel will be required.
The following instructions demonstrate how to build up state in a kernel and then return to that kernel using WolframScript:
1. Make sure to configure kernels that can stay alive indefinitely using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
"Pools":
{
"IBuildUpState":
{
"KeepAlive":true
}
}
}
2. Using the console, run wolframscript -wstpserver -startprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
3. Inside the WolframScript REPL, obtain the ID of the current kernel ID with WSTPServer`GetKernelID[]. The result is important: it will allow you to return to the current kernel later.
$ wolframscript -wstpserver -startprofile
In[1]:= WSTPServer`GetKernelID[]
Out[1]= a806-2645-9651
In[2]:=
In[10]:= WSTPServer`DisconnectKernel[]
$
7. Optionally, verify the ID of the currently bridged kernel with WSTPServer`GetKernelID[].
$ wolframscript -wstpserver -continueprofile
In[11]:= WSTPServer`GetKernelID[]
Out[11]= a806-2645-9651
In[12]:=
Using the WolframScript Profile Systems
WolframScript allows for the convenient reconnection to WSTPServer kernels. It is recommended that connections to specific kernels be tracked in profile files that the user must manage. WolframScript records in the profile file the ID of the kernel being used in order to allow reconnection to that kernel.
The section "DETAILS" of the program page "WolframScript" describes the profile system in greater detail, as well as the options -wstpserver, -startprofile and -continueprofile. The section "OPTIONS" provides a useful high-level overview of WolframScript's command-line options.
The following instructions demonstrate how to bridge to a kernel with specific properties using WolframScript:
1. Make sure to configure a kernel with the desired properties using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
"Pools":
{
"IHaveSpecificProperties":
{
"KeepAlive":true,
"ReservePreviouslyConnectedKernels":false
}
}
}
2. Create a profile file that contains the desired properties of the WSTPServer kernel.
# sampleprofile
KEEPALIVE=TRUE # I want a kernel with "KeepAlive" set to true
RESERVE=TRUE # I want a kernel with "ReservePreviouslyConnectedKernels" set to false
3. Using the console, run wolframscript -wstpserver -startprofile sampleprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
$ wolframscript -wstpserver -startprofile sampleprofile
In[1]:=
4. Inside the WolframScript REPL, make definitions and build up state.
In[1]:= x = 2 + 2
Out[1]:= 4
In[10]:= WSTPServer`DisconnectKernel[]
$
6. To return to the kernel obtained in step 3, run wolframscript -wstpserver -continueprofile sampleprofile.
$ wolframscript -wstpserver -continueprofile sampleprofile
In[11]:= x
Out[11]:= 4
Keep a Kernel Alive after Disconnecting from WSTPServer Contrary to Configuration
Typically, keeping a kernel alive after disconnecting from WSTPServer would require WSTPServer to be configured with the configuration file key KeepAlive set to true, but the Wolfram Language function WSTPServer`SetKeepAlive and the WSTP command SetKeepAlive can keep the currently bridged kernel alive indefinitely.
The following instructions demonstrate how keep the kernel alive even after unbridging with WSTPServer`SetKeepAlive and then return to that kernel using WolframScript:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, obtain the ID of the current kernel ID with WSTPServer`GetKernelID[]. The result is important: it will allow you to return to the current kernel later.
4. Return to the kernel by running wolframscript -wstpserver -continueprofile. If WSTPServer cannot be discovered, use the -wstpserver port@host option.
5. Inside the WolframScript REPL, optionally verify the ID of the currently bridged kernel with WSTPServer`GetKernelID[].
$ wolframscript -wstpserver -continueprofile
In[11]:= WSTPServer`GetKernelID[]
Out[11]= 825c-6cbd-129b
In[12]:=
Reserving a Kernel That Is Doing Important Work
It can be useful to only allow the current kernel, when unbridged, to be bridged to clients that request it by its ID. This will make it such that the current kernel will be available to users who need that kernel specifically, and it will protect the current kernel's session from users who do not need that specific kernel. This is the default behavior if the configuration file key ReservePreviouslyConnectedKernels is set to true.
The Wolfram Language function WSTPServer`SetReserveKernel or the WSTP command SetReserveKernel allows the current kernel to be reserved regardless of the value of ReservePreviouslyConnectedKernels. The following instructions demonstrate how to successfully reserve and safely unbridge from a kernel using WSTPServer`SetReserveKernel and the front end:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, reserve the kernel with WSTPServer`SetReserveKernel[True].
Monitoring WSTPServer
WSTPServer is a server program, so it can be useful to check its current state and get diagnostic information. The Wolfram Language function WSTPServer`GetServerInformation or the WSTP command GetServerInformation is provided for this purpose.
The following instructions demonstrate how to get information about the current state of WSTPServer using the front end:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, get information about the current state of WSTPServer with WSTPServer`GetServerInformation[].