Working with RTserver

The following sections discuss how RTserver works and how to configure RTserver. RTserver does not have any API functions that you can use, but it provides many options and commands for customizing the behavior of RTserver.

Setting Options

The primary way of configuring RTserver is through options in startup command files. This is especially important for RTserver, as RTserver can be automatically started by RTclient. If RTserver is not configured properly, it may not run correctly or even start at all. All RTserver startup command files and options are discussed in detail in Chapter 8, Options Reference.

Creating Connections

RTserver creates two distinct groups of connections. The first group of connections is specified in the option Conn_Names. These connections are server connections that are used by other processes (both RTclient and RTserver) to find this RTserver. The second group of connections is specified in the option Server_Names. These connections are client connections that are used to find other RTservers.

The maximum number of RTclients allowed to connect to an RTserver is specified by the RTserver option Max_Client_Conns. This option is useful for limiting the amount of publish-subscribe connection resources that each RTserver must provide.

Logical Connection Names

An RTserver uses logical connection names much like an RTclient. Because the usage is similar, only the differences in function are discussed in this section.

RTserver uses logical connection names in the options Conn_Names and Server_Names. RTserver uses the option Default_Protocols differently for Conn_Names. If a protocol is not listed in a name, then RTserver traverses the protocols in Default_Protocols and creates a server connection using each protocol. RTserver does not use any of the logical connection name modifiers of the type start prefix in either Conn_Names or Server_Names. RTserver never starts any RTclients or RTservers. RTserver supports _random, just like RTclient.

Logical Connection Name Modifiers

Each logical connection name in RTserver may be prefixed with one or more modifiers. The modifiers can be in any order and must be separated by a colon. For example:

modifier:modifier:protocol:node:address 

The modifier can be a keyword or a name-value pair, as in keyword:name=value:protocol:node:address. There are several logical connection name modifiers supported by RTserver including: connect modifier and connection cost modifier. RTclient supports the start prefix modifier.

Controlling How RTserver Connects to Other RTservers

Each logical connection name in RTserver can also have a connect modifier prefixed. A connect modifier is a keyword modifier. For example:

connect_modifier:protocol:node:address 

The connect modifier controls how an RTserver process tries to connect to other RTservers. When an RTserver connects to another RTserver process listed in the Server_Names option, the other RTserver responds with a list of other RTservers that the first RTserver may also connect to. The valid keywords for a connect modifier are:

If no connect modifier is specified in a logical connection name in the Server_Names option in RTserver, the connect modifier from the option Default_Connect_Prefix is used. The default value for Default_Connect_Prefix is connect_one.

Assigning a Cost to RTserver to RTserver Connections

Each logical connection name in RTserver can also have a cost modifier prefixed. A cost modifier is a name-value modifier.

For the purposes of dynamic message routing, each RTserver to RTserver connection is given a cost of one by default. This can be thought of as one hop between the RTservers at each end of the connection. However, the physical connections between two RTservers can vary greatly in terms of bandwidth, load, reliability and other attributes. A logical connection name listed in Server_Names can assign a cost to the physical connection that it represents. A cost of one is the default and is the least expensive cost that can be assigned to a connection. A cost greater than one will be factored into the lowest cost path message routing algorithm and will result in more message traffic being routed through other, less expensive, available connections. A cost is assigned to a connection by preceding a logical connection name with a cost modifier of the form cost=n, where n is a positive integer, separated by a colon:

cost=n:protocol:node_address 

For example, suppose the option Server_Names for RTserver on node shemp is set to:

cost=5:tcp:larry:8001,cost=2:tcp:curly:8001,cost=10:tcp:moe:8001 

If the RTservers are running on larry, curly and moe and do not attempt to connect to shemp then the RTserver on shemp would establish connections to RTservers on tcp port 8001 on the nodes larry, curly and moe. The RTserver connection between shemp and larry would be assigned a cost of five, the connection between shemp and curly a cost of two and the connection between shemp and moe a cost of ten.

If both RTservers on the ends of a connection try to assign a different cost to the connection, the results will be indeterminate. While traversing the Server_Names list, each RTserver will attempt to create the connection by making a connect request. One RTserver should connect successfully. The other RTserver should issue a successful accept. The second RTserver’s connect attempt will fail because the connection will already exist at that point. The RTserver whose connect succeeds will assign the cost to the connection. The cost will be one or the other cost, but it is indeterminate which one. So the RTserver that successfully initiates the connection has precedence if the two RTservers on each end of the connection try to assign different costs to the connection. See Lowest Cost Message Routing for more information.

Finding Other RTserver Processes

Because RTserver never starts any other RTclients or RTservers, it does not need any of the Server_Start_* options to control how it finds other RTservers. RTserver traverses the list of logical connection names in Server_Names once and uses each name to attempt to create a client connection to another RTserver process. If RTserver can connect to another RTserver process, it joins the existing group of multiple RTservers (see Multiple RTserver Processes for more details on this group). The RTserver connect and disconnect commands can be used to dynamically join and leave the group of multiple RTservers, and create and destroy connections to other RTservers.

Reconnecting to Other RTserver Processes

If an RTserver loses its connection or cannot connect to another RTserver process listed in the Server_Names option, it will automatically try to reconnect at a regular interval specified by the Server_Reconnect_Interval. Only the RTserver that makes the initial connection attempt will try the reconnect, otherwise temporary deadlock could occur if both RTservers simultaneously try to connect to each other. The automatic reconnection feature can be disabled by setting the option Server_Reconnect_Interval to 0.0.

Receiving and Processing Messages from RTclient

For most messages that RTserver receives from RTclient, RTserver looks at the destination property (a subject name) of the message and routes the message on to the RTclients subscribing to that subject. A few message types are processed locally, though. Table 13 lists the message types for which RTserver creates a process callback on the connections to RTclients.

Processing CONTROL Messages From RTclient

When RTserver receives a CONTROL message from RTclient, RTserver looks at the destination property (a subject name) of the message and routes the message on to the RTclients subscribing to that subject unless the destination is the unique subject of some RTserver or _server. If the destination is the unique subject of an RTserver, then the message is routed to that RTserver. If the destination is _server, RTserver uses the value of the option Enable_Control_Msgs to check if the command is enabled, and if allowed, then RTserver executes the command in the CONTROL message by calling the function TutCommandParseStr. This method allows RTserver to both route CONTROL messages and receive remote commands from RTclient. CONTROL and ADMIN_SET messages are the only message types that RTclient can explicitly publish to an RTserver. See Enable_Control_Msgs for details on how to properly configure CONTROL message security.

Message File Logging

As described in Message File Logging Categories, RTclient can log three categories of messages (data, status, and internal) to message files for incoming and outgoing messages. RTserver has a similar capability, but the message types are divided into only two categories:

Both standard and user-defined message types are logged, but user-defined message types are always logged using the verbose format (see Grammar for more information on the verbose message file format).

Logging Messages

RTserver starts and stops logging messages in the logging categories by setting these options: