Main Content

Configure Client-Server Communication

You can override the default configuration that MATLAB® Production Server™ add-ons use for client-server communication by setting environment variables and updating the MATLAB Production Server add-on configuration file located on the client machine. You might want to override the default configuration if your network is reliable, if your application is time critical, or if you want to change the server information for add-ons packaged into standalone executables.

Configure Timeouts and Retries

When you use MATLAB Client for MATLAB Production Server, the proxy functions in the MATLAB Production Server add-ons communicate with the functions of an archive deployed to a MATLAB Production Server instance. If the server takes too long to send a response, the client request times out. When a timeout occurs, the add-ons can report the error or silently try sending the request again.

MATLAB Production Server add-ons support two types of timeouts and one retry strategy. To override the default timeout durations and the default strategy for request retries, set MATLAB Production Server add-on environment variables.

Set Initial TCP Connection Timeout

Set the PROSERVER_ADDON_CONNECT_TIMEOUT environment variable to the number of seconds that an add-on function must wait before timing out when attempting to connect to a MATLAB Production Server instance. This is the initial TCP connection timeout.

By default, the operating system sets the TCP connection timeout value, typically, to 60 seconds or less, and might limit the value that you can set.

Typically, you do not need to set this value. If the server does not respond within the set time period, the add-ons generate an MPS:MATLAB:AddOn:RequestTimeout error.

Set Function Processing Timeout

Set the PRODSERVER_ADDON_FUNCTION_TIMEOUT environment variable to the number of seconds that an add-on function must wait for the deployed function to complete processing, which includes making the initial connection, and returning a response to the client.

The default behavior is to wait forever for the function to finish processing and never time out.

If your network is reliable or your application is time critical, you might set the environment variable so that the client request can time out earlier. Since the processing time for the add-on function includes the time to make a TCP connection with the server, do not set PRODSERVER_ADDON_FUNCTION_TIMEOUT to a non-zero value smaller than PRODSERVER_ADDON_CONNECT_TIMEOUT. If the deployed function does not return a complete response within the timeout value that you set, an MPS:MATLAB:AddOn:RequestTimeout error occurs.

Configure Function Retries

Set the PRODSERVER_ADDON_FUNCTION_RETRIES environment variable to the number of times that an add-on retries a single function call that times out. The add-on retries only those functions that time out. The add-on generates an error if a function fails for any other reason.

The default behavior specifies not to retry functions that time out and to report MPS:MATLAB:AddOn:RequestTimeout errors on the first timeout.

If the number of timeouts exceeds the value that you set, the add-on reports an MPS:MATLAB:AddOn:RequestTimeout error.

Set Environment Variables

To control the timeouts in a MATLAB session, set the environment variables using the setenv (MATLAB) function. For example:

Retry three times on timeout for the MATLAB function mandelflake:

>> setenv('PRODSERVER_ADDON_FUNCTION_RETRIES','3')
>> mandelflake

To control the timeouts in a standalone executable or software component, set the environment variables using commands specific to your operating system, typically setenv on Linux® and macOS, and set on Windows®. For example:

  • Retry three times on timeout for the Linux standalone executable mandelflake:

    % setenv PRODSERVER_ADDON_FUNCTION_RETRIES 3
    % mandelflake

  • Retry three times on timeout for a Windows standalone executable mandelflake.exe:

    C:\> set PRODSERVER_ADDON_FUNCTION_RETRIES=3
    C:\> mandelflake.exe
    

Update Server Configuration

The MATLAB Production Server add-on configuration file specifies the association and dependency between the MATLAB Production Server add-on proxy functions and the MATLAB Production Server deployable archives from which you install the proxy functions. By default, the add-on proxy functions communicate with the MATLAB Production Server instance from which you install them. If the network address or the application access control configuration of the server instance changes, you can modify the configuration file to include the updated server information. For example, the network address of the server can change if you move from a testing environment to a production environment. The access control configuration can change if the Azure® AD app registration credentials of the server change.

The configuration file lets you easily change server-specific information without rebuilding the deployable archive or reinstalling the add-on, since the mapping between an add-on and an archive is in the configuration file that is external to both. This external mapping is especially useful when you want to change the server information for add-on proxy functions that are packaged into a standalone executable or deployable software component, since standalone executables and deployable software components can also be shared and used on machines that are different from those that package them.

Update Add-On Configuration File

The default name of the add-on configuration file is prodserver_addon_config.json. A sample configuration file follows.

{
  "Installed": {
    "Scheme": "http",
    "Host": "localhost",
    "Port": 9990,
    "Config": {
        "AccessTokenPolicy":"none",
        "ClientID": "",
        "IssuerURI": "",
        "ServerID": ""
     },
    "AddOns": {
          "name": "fractal (R2020b)",
          "uuid": "e3325lo6-4297-47d2-9ec8-9df64195fce3",
          "archiveID": "fractal_311a3f55107d8d603cc3d91707bf2feb"
    }
  },
  "SchemaVersion": 1.2
}

The sample configuration file describes a single add-on fractal that requires MATLAB Runtime version R2020b and a deployable archive fractal hosted by a MATLAB Production Server instance at network address locahost:9990.

To update the network address of the server, update the values corresponding to the Host and Port fields. To update the access control configuration of the server, update the values in the Config object. If you do not manage the server, you can obtain these values from the server administrator. For more information about configuring access control when using the add-ons, see Application Access Control.

Update Add-On Configuration File Location

The default location of the add-on configuration file is in the MATLAB user preference directory of the machine on which the add-on function is installed. To locate the preferences directory on your machine, run prefdir (MATLAB) at the MATLAB command prompt.

You can save the add-on configuration file in a different location and also change the name of the add-on configuration file. To specify a different location or name than the default, set the PRODSERVER_ADDON_CONFIG environment variable. When setting the variable, you must specify the full path to the file from the root of the file system. You might save the add-on configuration file in a different location when you want to update the server configuration for add-on proxy functions that are packaged into standalone executables or shared components.

Related Topics