Wolfram Language & System Documentation Center
WSTPServer

NAME

wstpserver — a server program to launch and maintain Wolfram Language kernels for incoming WSTP connections

SYNOPSIS

wstpserver [--port port] [--interface interface]

DESCRIPTION

WSTPServer manages kernels and kernel pools.

WSTPServer routes all traffic from a client to a kernel that it manages, allowing links to WSTPServer to behave as direct links to kernels. This process is highly configurable: for example, a client can connect to a kernel it has connected to previously, or a client can connect to a different kernel on every connection.

OPTIONS

    OPTIONS

    The command-line options for WSTPServer are the following:

  • -h, --helpprint help text
    -l, --log-level nspecify the level of verbosity of messages
    -f, --log-file fileNullwrite messages to a specified file
    -a, --advertise [serviceNullif present, advertise the link server as the specified service
    -p, --port portlisten on the specified port
    -i, --interface interfacelisten on the specified interface
    -c, --configuration-file fileuse the specified configuration file

    • The three levels of verbosity of --log-level and -l are the following:

  • error, 1report server startup/shutdown errors and print a successful startup message
    debug, 2report everything from level 1 and all debug messages
    trace, 3report everything from level 2 and all handled WSTP traffic

    • If --log-level or -l is not used, the default logging verbosity is set to error.

    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 --advertise or -a is not used, the link server will not be advertised.

    If --port or -p is not used, the link server will listen on the port 31415.

    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.

DETAILS

EXAMPLES

Start WSTPServer with a simple command:

$ 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

...

Start WSTPServer so that it listens on port 12345 on the loopback interface:

$ wstpserver --port 12345 --interface 127.0.0.1

WSTPServer: Logger (0, 2020-09-29 16:54:25): Information: 
    Using "/Applications/Mathematica.app/Contents/MacOS/WolframKernel" as a default kernel path

WSTPServer: Logger (0, 2020-09-29 16:54:29): Information: 
    Listening for new connections on port 12345 and interface 127.0.0.1

...

FILES

Default configuration file:

  • %APPDATA%\WSTPServer\wstpserver.conf
    		Windows
    ~/Library/Application Support/WSTPServer/wstpserver.conf
    		Macintosh
    ~/.config/WSTPServer/wstpserver.conf
    		Linux

    • "Introduction to WSTPServer" provides further information in the section "Configuration File".

    WOLFRAM LANGUAGE FUNCTIONS

    WSTPServer`StartKernel — Start a kernel (outside of any pools), and return its ID.

    WSTPServer`CloseKernel — Close a kernel.

    WSTPServer`ConnectKernel — Bridge the current connection with the specified kernel.

    WSTPServer`DisconnectKernel — Unbridge the current connection with its bridged kernel.

    WSTPServer`SetKeepAlive — Set whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends.

    WSTPServer`SetAllowSilentKernelReplacement— Set whether to allow or disallow the silent restart of the kernel bridged to the current connection if the kernel dies.

    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 all information about all pools and all kernels.

    WSTPServer`SetReserveKernel — Set whether the current kernel, when unbridged, can only be bridged to clients that request it by ID.

    "Introduction to WSTPServer" provides further information in the section "Command Language".

    ENVIRONMENT VARIABLES

    WSTPSERVER_CONFIGURATION_FILE — A path to a specific configuration file to use instead of the default configuration file search behavior.

    WSTPSERVER_PORT — If set, the port for the link server to listen on.

    WSTPSERVER_INTERFACE — If set, the interface for the link server to listen on.

    WSTPSERVER_DISABLE_ADVERTISING — If set, disable advertising the link server.

    CONFIGURATION VARIABLES

    "Introduction to WSTPServer" provides possible configuration variables and further information in the section "Configuration File".