| The LotusScript RunOnServer method allows an agent called from a Notes client to run on the Domino server rather than on the client. Running on the client is the default behavior when running an agent from the Notes client.
Running on the client results in isolation of the agent. As each client has its own memory, the agent run by one user does not interact with the memory of any other user. If an agent were scheduled rather than invoked by the client, each agent run would have its own memory environment in the AMGR task running on Domino. To run concurrently scheduled agents requires running multiple AMgr tasks, each with its own memory.
The RunOnServer method forces the agent to run in the SERVER task. This introduces a number of complexities, detailed below.
Multi-threaded environment
The SERVER task support many user sessions, as such more than 1 user may attempt to run the same agent at the same time. If the agent is not thread safe this can result in critical failure, including data loss and or server crash. Each LotusScript function lists if it is thread safe. Test your application under load prior to moving to production.
Memory Management
Agents run in AMgr or on the client have managed memory. Each time an agent ends in AMgr, the task ends, clearing any memory that the agent left allocated. On the client, agent usage is low enough that any memory left allocated usually does not lead to memory problems. RunOnServer runs in the SERVER task. This task does not manage agent memory, so even a small memory leak in an agent can result in performance issues or a server crash due to memory exhaustion.
LotusScript is a design language, and it is up to the agent designer to manage memory. The server will not manage memory for the developer.
In some cases, an agent that has worked for years will start crashing the server. This can be due to increases in load (users or documents) that result in memory exhaustion. This is the most commonly reported client issue around RUNONSERVER
CPU usage
An agent running in AMGR is limited by the server rules for agents, including time allowed to run and time of day, as well as a limit on concurrent agents. Agents run via RunOnServer are only limited by the number of threads in the server task pool. The server task pool limits the number of concurrent requests that can be processed. A high number of complex agents running concurrently can overrun your system CPU(s) and create a performance issue on the server. Always test based on the maximum number of users that can run the agent. If your system cannot support using all threads to run the agent concurrently, do not allow the agent to invoke RunOnServer.
Document management
In single-threaded designs, an agent working on a document or group of documents has exclusive access to the data. In concurrent agent design it must be considered that more than one user might cause the agent to act on the same data concurrently. If required, document locking should be enabled to ensure correct processing of your data.
Limits of concurrent agents in Domino
While RunOnServer may allow more agents to run concurrently than is possible through AMgr, there are still finite limits. No more than 65,535 agents can be run concurrently, assuming unlimited resources. In practice, memory management will limit scalability well below this high number. To understand the limits of your applications stability consider dumping memory usage during load.
|