Introduction
Pathway application programming is prevalent in most NonStop customer environments. The requester/server model (known today as “client/server”) is fundamental to the NonStop in general and to Pathway specifically. Clients send requests to Servers; a Server processes the request and returns a response; the Client then processes the response.
LightWave Server (LWS) generally interacts with customer applications through the NonStop Pathsend facility. LWS uses Pathsend operations to send requests from RESTful clients to a Pathway server application.
This article explains the link management, its configuration, and its effects on LightWave Server request processing.
ACS Subsystem Core Processes
Together with the PATHMON process, the ACS subsystem controls communication between LWS and application serverclass processes.
Each processor (CPU) contains one set of ACS core processes (Redirector (ROUT), PB, and configuration subscriber (CS) programs running as $ZLnn , $ZPnn , and $ZCSnn processes respectively, where nn is the CPU number), which are responsible for all Pathsend requesters executing in that processor.
(The CS process and related ACS functionality is beyond the scope of this article.)
ACS subsystem core processes acquire links from the PATHMON process that controls the serverclass. The ROUT process then shares the links among the Pathsend requesters (such as LWS) executing in its CPU.
For example, link management for a Pathsend request from a process running in CPU 0 would be managed by $ZL00 and $ZP00 even if the serverclass processes run in different CPUs. ROUT, PB and PATHMON “negotiate” the grant of a link to the ROUT process. The ROUT process then establishes an IPC connection to the serverclass process.
Interprocess Communication Initiation
Communication between requesters such as LWS and application servers in a Pathsend environment differs from that between Guardian requesters and servers. Rather than directly opening a specific server process, a LWS process opens the ROUT process indirectly via a Pathsend call such as SERVERCLASS_SEND_.
ROUT in turn opens a serverclass process selected by the PATHMON process. ROUT’s open of the server process is shared among all requesters running in the same processor as the ROUT process.
A typical communication session begins as follows:
- LWS calls SERVERCLASS_SEND_ to request a server-class send operation.
- The request goes to the ROUT process running in the same processor as the LWS process.
- The ROUT and PB processes check for a link to a server process in the server-class specified in the request. If the ROUT and PB process have no available link to the server-class, the actions performed depend on the settings of the PATHMON configuration parameters NUMSTATIC and MAXLINKS. Following steps might occur:
- The PB process sends a “get-link” request to the PATHMON process that manages the serverclass specified in the procedure call.
- The PATHMON process selects a server process in the specified serverclass. If necessary, it starts and initializes a new server process in the serverclass.
- The PATHMON process returns the Guardian process name of a server process within the specified serverclass to the PB process.
- The ROUT process opens the server process of that name. This open is shared among all the Pathsend requestor processes running in the same processor as that ROUT process; therefore, a close operation does not necessarily occur when the communication with a particular requestor process is finished.
- The ROUT process forwards the send request to the server process.
- When the server process replies, the ROUT process replies to the requestor process, and the serverclass send operation is complete.
- Additional SERVERCLASS_SEND_ calls from the same LWS process to the same serverclass will use the same link.
The action of the PATHMON process in step 3 is called "granting a link." The ACS subsystem processes, which request links and provide access to the server process after the link is granted, is called the link manager.
Link Management
As described earlier, a Pathway “link” is an interprocess communication connection between a link manager and a specific Pathway server process.
A link manager attempts to use one of its existing links to satisfy a request. Failing that, it asks for a new static link. If no static links are available, and no static link becomes available within the time specified by CREATEDELAY, then it asks for a dynamic link.
PATHMON will use all available links, either static or dynamic, before starting a new server process. All links to static servers are allocated first, then all links for each dynamic server (indicated by MAXLINKS are allocated) before starting a new dynamic server.
If there are no links available, PATHMON generates a 1034 error (no links available) log message for the first occurrence of the problem for the serverclass. This is also the time at which PATHMON marks the serverclass with error 1034.
Link Configuration
Every Pathway serverclass has six attributes that affect its relationship with the ACS susbsytem’s link management:
- MAXSERVERS
- MAXLINKS
- LINKDEPTH
- NUMSTATIC
- CREATEDELAY and DELETEDELAY
The value of the PATHWAY MAXSERVERPROCESSES also affects link configuration in that it specifies the maximum number of processes for all serverclasses in a PATHMON environment.
MAXSERVERS
The MAXSERVERS attribute specifies the maximum number of processes that can run concurrently in a serverclass.
To determine the maximum number of links available in a serverclass, use the formula:
MAXSERVERS * MAXLINKS
MAXLINKS
The MAXLINKS attribute specifies the maximum number of links to an instance of a server process from all link managers in the system. While the server process is handling a request, a number of new requests up to the value of MAXLINKS minus 1 can queue at the server.
LINKDEPTH
The LINKDEPTH attribute specifies the maximum number of links that any one link manager can have to an individual server process in a serverclass. (Link managers can also have links to other server processes in the serverclass.)
If LINKDEPTH is 1, each link manager can have only one link to each server process. Each request to the PATHMON process for an additional link results in a link to a different server process. Each link results in a single open of the server. The link manager makes the server open available for use by multiple Pathsend requesters.
Normally, only server programs coded to use NOWAIT I/O have a LINKDEPTH value greater than 1. Setting the LINKDEPTH value greater than 1 for a WAITED serverclass can lead to queuing at the server process and increased response time.
NUMSTATIC
The NUMSTATIC attribute specifies the maximum number of static servers within a serverclass.
The ACS link manager and PATHMON will grant all available static links for a serverclass before creating a new process.
The value of MAXSERVERS minus the value of NUMSTATIC equals the number of dynamic server processes in the serverclass.
The maximum number of static links that a link manager ACS subsystem processes can have is determined by the formula:
NUMSTATIC * LINKDEPTH
CREATEDELAY and DELETEDELAY
CREATEDELAY is the length of time a send request queues before the link manager asks for another link, assuming the link manager has determined that no more static links are available.
A link manager will always ask for a link immediately if the link manager has determined that static links are still available.
The DELETEDELAY attribute specifies the amount of time that a dynamic server sits idle before the link manager returns the link to the PATHMON process.
Example Effects of Link Configuration
Many factors must be considered for optimal Pathway configuration, though these general examples may help illustrate how Pathway link attributes can affect LWS throughput:
- If the server attribute LINKDEPTH is set to 20, that permits 20 concurrent requests to a server process. If transaction service time is 1 second and the serverclass handles requests serially, response time might be as long as 20 seconds. This LINKDEPTH setting can cause LWS Pathsend requests to queue on the serverclass for unacceptable lengths of time.
- If the server attributes MAXLINKS and MAXSERVERS are set to 1, indicating that only one server process can run in this class at a time, and this setting proves too low for the request volume, LWS requests might queue for the link manager because the PATHMON process cannot create another server process to satisfy the link requests.
- If MAXLINKS is set to 5, MAXSERVERS is set to 1, and LINKDEPTH is set to 1, that specifies that a maximum of five links to each serverclass process is allowed; each link manager (ROUT/PB) can have only one link to each process in the serverclass, and only one server process can run in the class at any one time. If an ACS subsystem process is managing link requests from five LWS processes, and each process sends a request to this serverclass, four LWS processes must wait for the link to become available.
Summary
The effects of ACS subsystem link management on LightWave Server are the same as they would be for any other Pathsend requester.
Note that LWS SERVER and SWORKER processes targeting a given PATHMON/Serverclass Name share the available links to it with other LWS processes and with other Pathsend requesters also targeting that serverclass. If LWS is sharing application services this should be taken into consideration when configuring the serverclass.
The LWS interaction follows the same general pattern as described earlier:
- A RESTful API request is received by the LWS SERVER process (and “handed off” to a SWORKER process, if any are configured).
- LWS references the API definition for the request to determine the target PATHMON and Serverclass Name. The request payload is deserialized into an IPM.
- LWS initiates a SERVERCLASS_SEND_ of the IPM to the application server process.
- If an existing link is available for the ROUT process (in the LWS process’s CPU), the request is queued to the application server through that ROUT process.
- How long the request stays queued depends on whether and how fast the server process replies.
- If no links are available, the SERVERCLASS_SEND_ immediately fails with an error code of 905 (No Serverclass Links Available). The error results in LWS returning an HTTP status 500 to the RESTful client; with specific error codes and a text message returned in HTTP header fields, as described in LWS Documentation.
- If a no link available error has not yet occurred for the serverclass, PATHMON generates a log 1034 error message and marks the serverclass with error 1034.
- Note that requests stay queued until the serverclass process responds or it is stopped. If the server process is stopped, the ACS link manager returns a SERVERCLASS_SEND_ error to LWS.
Note that LWS will not cancel or timeout a queued Pathsend request unless the client drops the socket.
If the serverclass process stops after reading the request from its $RECEIVE queue and before replying to the request, ROUT returns a 904 error code for the SERVERCLASS_SEND_, with the Guardian error code set to 201. (These values are returned by LWS in the HTTP response headers as described in the LWS Documentation.)
References
LightWave Server Documentation, NuWave Technologies, March 2023
TS/MP 2.7 ACS Reference Manual, Hewlett-Packard Enterprise, June 2018
TS/MP 2.8 ACS User Guide, HPE, September 2022
TS/MP 2.8 Pathsend and Server Programming Manual, HPE, June 2021
TS/MP 2.8 System Administrator Guide, HPE, September 2022