Services Pool (GWS Only)

Requests for Web services are processed by the GWS proxy and are managed using the DVM pool. The examples will assist you in configuring the pool element of your web service.

Why do we need Services Pool for GWS?

A Dynamic Virtual Machine (DVM) can only support one application at a time. As a result, the GWS proxy needs to launch a new DVM (an fglrun process) for each request on the web server. If traffic to a web server was to become very high – with hundreds of requests at any period – this could result in slow response time or even overloading of the web server.

To avoid unnecessary use of resources and to respond as fast as possible to client requests, the GWS proxy manages DVM processes in a pool. From the pool it can release inactive DVMs or launch new ones, up to the maximum number of DVM processes specified for the application. These parameters are defined in the POOL element of the Genero Application Server configuration file.

Important:

When sticky mode is used, the POOL is disregarded. The MAX_AVAILABLE setting limiting the number of DVMs available to the web service is no longer taken into account. It is recommended to handle the stopping of the sticky web service in your application code with a dedicated method to be called by the user agent when it needs to close the session.

Releasing DVMs not Actively Processing Requests

Genero web service DVMs are not shutdown immediately after they stop processing requests. Instead DVM shutdown is optimized by the gwsproxy from request statistics and frequency of use that best determine the use of resources at runtime. The gwsproxy calculates this based on a combination of the following factors:
Time to Start a New DVM
The gwsproxy waits at least the time it takes to start a new DVM before deciding if a DVM can be shutdown.
Three Times the Last Request Execution Time
If their is only one request, a DVM shutdown takes place after waiting three times the request execution time from when the last request took place.
Three Times the Average Request Frequency
If there is more than one request, a DVM is shutdown after waiting three times the average request frequency. For example, the GWS proxy calculates the elapsed time since it received the last new incoming request. If this is three times greater than the average frequency of new requests it has been receiving, it stops one inactive DVM.
The time to shutdown a DVM will therefore vary depending on how great the web service's request load has been for the previous period. Eventually DVMs are released to reach the value specified by MIN_AVAILABLE because the gwsproxy calculation is also bound by a minimum (one second) and a maximum (ten minutes) limit.
Minimum (one second)
If time to shutdown is less than one second, the gwsproxy waits a full one second before shutting down the DVM.
Maximum (ten minutes)
If time to shutdown is more than ten minutes, the gwsproxy waits no longer than ten minutes before shutting down a DVM.
If the GAS is properly shutting down DVMs that are not needed, the GWS server will return the specific error code (-15575) for this, and the following message will be written to the logs:
Stopping Service: -15575 - Incoming request has been closed : Disconnected by GAS.

Understand DVM_AVAILABLE

The web service invalidation feature will mark an service's configuration as bad if the gwsproxy cannot start a DVM within the time set by DVM_AVAILABLE. Once the service's configuration is marked as bad, that service will not be accessible until the issue has been addressed by an administrator. If DVM_AVAILABLE is being reached due to activity on the system that is not related to the web service (a nighttime backup, for example), you will need to make adjustments to keep your service's configuration from being marked as bad. This could include
  • Increasing the time allowed to start the DVM by increasing DVM_AVAILABLE.
  • Removing KEEP_ALIVE (or setting it to a large value) to ensure that the gwsproxy does not shut down, allowing the MIN_AVAILABLE DVMs to remain active.
  • Fixing the issue that prevents the web service from starting in the DVM_AVAILABLE time frame.
See Web service invalidation for details on correcting a configuration identified as bad.

Understand KEEP_ALIVE

The KEEP_ALIVE setting is a means to prevent the gwsproxy for a given web service, and the DVMs it manages, running indefinitely when inactive. The default value for the KEEP_ALIVE timeout is 3600 seconds or one hour. After this period of inactivity, the KEEP_ALIVE timeout is triggered and the GAS shuts down the web service's gwsproxy and DVMs.

If the KEEP_ALIVE timeout is shutting down the gwsproxy due to inactivity, you will see the following message in the gwsproxy logs:
Server stopped due to stop command.
In the corresponding vm logs, you should see the GWS server returns a specific error code (-15575) for shutting down the inactive DVMs with a message similar to the following:
Stopping Service: -15575 - Incoming request has been closed : Disconnected by GAS.

In most cases, you need KEEP_ALIVE to prevent inactive gwsproxy and DVMs running indefinitely and wasting system resources. Yet, there may be times when you need the service to remain active, such as when that service is providing authentication for users, or in the management of user licenses, you need to ensure a license is available for the service. Then you must remove KEEP_ALIVE (or set it to a large value) to ensure that the gwsproxy does not shut down. This will allow the MIN_AVAILABLE DVMs to remain active.

Example 1: One GWSProxy Starts three DVMs

Assume the following values have been specified for a web service application:
<POOL>
  <START>3</START>
  <MIN_AVAILABLE>2</MIN_AVAILABLE>
  <MAX_AVAILABLE>5</MAX_AVAILABLE>
</POOL>

When the Genero Application Server first starts, the START element defines how many DVMs to start for a particular web service. There is one GWSProxy in charge of the pool of DVMs for the web service. For our example, this means that one GWSProxy will launch three DVMs.


The figure shows one GWSProxy launching three DVMs.

Example 2: GWSProxy Launches new DVMs when Required up to MAX_AVAILABLE

As requests come in, the GWS proxy determines whether there is a need to start up new DVMs. For the number of pending requests in the queue, the GWS proxy computes the average request execution time against the time to start a DVM. If dispatching all pending requests over the active DVMs takes less time than starting a new DVM, no new DVM will be started. In other words, a new DVM will only be started if it will help to decrease the waiting time of all pending requests. At most, MAX_AVAILABLE DVMs can be started.

Continuing with our example, up to five DVMs can be launched to handle requests.


The figure shows one GWSProxy launching / managing six DVMs, the limit being set by MAX_AVAILABLE configuration parameter.

Example 3: GWSProxy Manages a Connection Queue

What happens when there are MAX_AVAILABLE DVMs actively processing requests, and a new request comes in? The new request is placed in a connection queue, waiting for a DVM to become available. The new requests could (in theory) be waiting indefinitely, except:

  • There is the option of a timeout in the web server to handle infinite wait.

  • Any web service client can define its own timeout limit. If a client is willing to wait indefinitely for a web service response, it is permitted.

Continuing with our example, this means that if all five DVMs are actively processing requests, and a sixth requests comes in, that request is placed in the connection queue until a DVM is available to process the request, or a timeout is reached based on settings in either the web server or the web service client.


The figure shows one GWSProxy launching / managing five DVMs. In addition, the Connection Queue joins the workflow at the GWSProxy.

Example 4: GWSProxy Releases Inactive DVMs

While the START element defines the number of DVMs to start initially, DVMs that are not actively processing requests can be released based on GAS statistics. For example, the GWSproxy calculates the elapsed time since it received the last new incoming request. If this is three times greater than the average frequency of new requests it has been receiving, it stops one inactive DVM. See Releasing DVMs not Actively Processing Requests.

Continuing with our example, if all of the DVMs are not actively processing requests, then one DVM will eventually be released, bringing the total number of DVMs to the MIN_AVAILABLE amount of two.


The figure shows one GWSProxy launching / managing two DVMs, the limit being set by MIN_AVAILABLE configuration parameter.

Example 5: GWSProxy stops after KEEP_ALIVE inactivity

Assume the following values have been specified for a web service application:
<POOL>
  <START>2</START>
  <MIN_AVAILABLE>1</MIN_AVAILABLE>
  <MAX_AVAILABLE>5</MAX_AVAILABLE>
</POOL>

What happens when DVMs are no longer processing requests, and no new requests are coming in?

Continuing with our example, if none of the DVMs are actively processing requests, then the DVMs will eventually be released, bringing the total number of DVMs to the MIN_AVAILABLE amount of one.

If the inactivity continues for the time set by the KEEP_ALIVE timeout, then the GAS shuts down the GWSProxy and the remaining MIN_AVAILABLE DVMs. See Understand KEEP_ALIVE.


The figure shows one GWSProxy and DVM being shut down by the timeout set by the KEEP_ALIVE configuration parameter.