Before describing how on-demand results retrieval can impact memory management on the client host, it is helpful to know how results are processed in Symphony’s default model.
Since the underlying communication channel between the client and the Symphony Session Manager is asynchronous, results are sent to the client as soon as they are available. If the client makes a request for results before they arrive, the client code is blocked until the results arrive or the wait period expires. If the results arrive before the client makes a request, the results are queued (cached) in the local session’s result set. Since the delivery of results from the Symphony Session Manager is not in sync with the retrieval of results, it is possible that too many results could be queued in the API layer; this could cause the client to run out of memory and eventually terminate abnormally.
The purpose of the on-demand results retrieval feature is to control the retrieval of results so that the client is not overloaded with results and runs out of memory. This is achieved by having the client retrieve data directly from the Symphony Session Manager instead of from the local result cache. To better understand the interaction between the client and the Symphony Session Manager, let’s look at the sequence of events.
Symphony Session Manager gets the result from the service and defers dispatching it to the client.
Client makes an API call to request the next result set from the Symphony Session Manager.
The Symphony Session Manager returns as much of the result set that it has available, i.e., 0-N, to the client.
The on-demand results retrieval feature can only be accessed through the client API. To use this feature, the client application must perform the following sequence:
The session flag is a member of the SessionCreationAttributes class. The following list shows how the session flag is set for on-demand results retrieval in each supported language.
Normally the Session.FetchTaskOutput(ulong countMax) method blocks indefinitely until countMax task responses are ready. When your session is created using the FetchResultsDirectly flag, the call does not block indefinitely but instead returns with 0 - N items. The number of items returned depends on the amount of results available in the Symphony Session Manager at the time of the call. Therefore, the client must poll until the desired number of results have returned.
If the Session.FetchTaskOutput(ulong countMax, long timeoutInSeconds) method is used while the on-demand results retrieval feature is enabled, the timeout parameter is ignored by the Symphony Session Manager.