3. Configuring Gem Session Processes
This chapter tells how to configure the GemStone/S 64 Bit session processes for your application. For additional information about running session processes on a node remote from the Stone repository monitor, refer also to Chapter 5.
3.1 Overview
As shown in Figure 3.1, a GemStone session involves the following components in a client-server relationship:
- The user’s client Application
- The Gem, which acts as a server for a particular application. The Gem can be a separate session process, or linked to the client application.
- The Stone repository monitor, and other server processes.
- The shared page cache (shared memory segment), and the shared page cache monitor process.
- The repository extent files
Figure 3.1 GemStone Session Elements
From the point of view of the application, the Gem is the object server; it provides the bulk of the repository capabilities:
- It logs in to the repository with the Stone, and it obtains object locks, free object identifiers, and free pages from the Stone.
- It presents the application with a consistent view of the repository during a transaction, and tracks which objects the application accesses.
- It executes Smalltalk methods within the repository.
- It reads the repository as the application accesses objects, and (with the help of the AIO page server) it updates the repository when the application successfully commits a transaction.
Linked and RPC Applications
The Gem session process can be run as a separate process (the RPC Gem in Figure 3.1) or integrated with the application into a single process, in which case the application is called a linked application (the Linked Gem in Figure 3.1) .
When the Gem runs as a separate process, it responds to Remote Procedure Calls (RPCs) from the application; this is called an RPC application. Applications that use a separate Gem process start that process automatically (from the user’s viewpoint) while logging in to the repository.
Either type of application can be used on a single node or across a network.
An application can have only one linked login, since only one Gem can be integrated with the process. Any application may have multiple RPC logins, or one linked and multiple RPC logins.
GemStone provides both linked and RPC versions of topaz for repository administration, and shared client libraries that allow linked and RPC. The linked version allows both linked and RPC logins, but the RPC version allows only RPC logins.
C programmers should always use an RPC version during development and debugging to protect Gem data structures from possible corruption.
Note on terminology
The term “Gem” is used to refer to both the linked and RPC sessions, although only one of these is a separate OS process. Both normally represent a logged in session in GemStone, and from the Stone’s point of view, there is little difference.
The term “session” is also sometimes used interchangeably with “Gem”. However, multi-threaded operations such as for backup and garbage collection may allow multiple threads within a Gem process to log in individual sessions.
The Session Configuration File
At start-up time, each Gem session process looks for a configuration file, which by default is the same system-wide configuration file used by the repository monitor when it starts. However, there are three important differences:
- Session configuration details are optional. If no configuration file is not found, the session process uses system defaults.
- All session processes read those configuration options that begin with “GEM_” and the few that are used by both Stones and Gems (such as DUMP_OPTIONS and LOG_WARNINGS). Other settings that the Gem needs are obtained from the Stone and are the same for all sessions logged in to that Stone.
- When a Gem is started on a remote node (i.e., a node other than the node on which the Stone and extents are), and there is not already a shared page cache on that node, then the configuration options (SHR_) will determine the configuration of the remote cache.
Different applications and utilities that use the same repository may need different Gem configurations. For example, batch file processes may requires a much larger amount of temporary object memory. Appendix A, “GemStone Configuration Options” describes how to specify an alternate configuration file and how to use supplementary files to adjust the system-wide configuration for a specific session process. These settings may also be passed as arguments to the Gem or to Topaz.
3.2 Configuring Gem Session Processes
In addition to configuring the Gem itself, you must determine where the Gem will be running, and ensure that any other required processes are configured correctly.
Local vs. Remote
The first step in establishing the Gem Session configuration is determining where your Gems will be running.
Local
If you intend the Gem processes or linked applications to run on the same machine as the Stone, this node needs to have sufficient resources above what is needed for the server itself.
Each Gem you plan on running requires memory as described under Gem Memory Requirements.
Remote
When one or more Gems will be remote (that is, running on a different node than the Stone) you will need to set the configuration that will be used on the remote node. Each remote node must be setup to run the required GemStone processes.
On a remote node, the first Gem to login will initiate the startup of the remote shared page cache, and this Gem’s configuration will be used to configure the remote shared page cache.
In addition to the memory required for each Gem, as described under Gem Memory Requirements, you must have sufficient resources to run a remote shared page cache, cache monitor process, and other server processes. See Server Components to review these requirements.
Gem Memory Requirements
The amount of memory required by a Gem session is dependent on how it is configured, as determined by the system requirements. To avoid out-of-memory conditions, Gems must be configured with an adequate temporary object cache. The default of 50MB is suitable for light use; it is likely that particular operations in an application will require more, possibly much more.
With the 50 MB default Gem’s temporary object cache, the first Gem session process or linked application on a node ordinarily requires about 80 MB of memory, of which 5 MB is for code that can be shared by other session processes. Each additional session process requires about 65 MB.
If you tune the cache size for Gems, add any increase to the amount given here.
More details are provided in Configure Temporary Object Space, and Chapter 13, “Managing Memory”.
Additional Configuration for Remote Gems
The configuration file used by Gem sessions will also be used, on remote nodes, to configure the associated remote shared page cache monitor.
The Stone always creates a shared page cache monitor and cache on its own node, based on parameters in the Stone’s configuration file. This cache is always used by Gems that run on this node.
On other nodes, when the first Gem session process logs in, if there is not already a shared page cache running on that remote node, a remote cache is started. Parameters specified for the first Gem that logs in determine the size of the cache and the number of processes that can attach to it (SHR_PAGE_CACHE_SIZE_KB and SHR_PAGE_CACHE_NUM_PROCS, respectively). These configuration parameter settings usually come from the Gem’s configuration file, but may also be specified by Topaz arguments or arguments with the Gem’s NRS.
All subsequent sessions that log in from that remote node will use the same cache.
3.3 Set the Gem Configuration Options
There are a number of configuration options for Gem session processes.
Configure Temporary Object Space
Gems use temporary object memory for a number of purposes, described in detail in Chapter 13. The upper limit on this memory is configured by the GEM_TEMPOBJ_CACHE_SIZE configuration option. It is important to provide sufficient temporary object space. If temporary object memory is exhausted, the Gem can encounter an out-of-memory condition and terminate.
The default of 50000 (50 MB) should be adequate for normal user sessions. For sessions that place a high demand on the temporary object cache, modifying large numbers of objects or working with large collections, a large value will be needed.
The configured value must be large enough to accommodate the memory needs of any gem using that configuration. The amount of temporary object memory required may be different for different application gems, depending on the specific tasks of the gem; you may wish to set up special configuration files for application sessions that have a particularly high demand on memory.
The full amount of GEM_TEMPOBJ_CACHE_SIZE is not allocated on gem login, but it is reserved and will impact memory usage per user.
The configured size of the Stone’s shared page cache plus temporary object memory size should not be greater than the amount of memory available on the machine on which the Gem will be running, allowing for overhead for the operating system and other GemStone requirements. The Gem temporary object cache should also be smaller than the size of the Stone’s shared page cache, otherwise it may be impossible for operations such as commit to execute.
You will probably need to experiment somewhat before you determine the optimum size of the temporary object space.
Memory management is discussed in greater detail in Chapter 13, “Managing Memory”.
Configure SSL for remote Gem sessions
During the RPC login process, a Secure Socket Layer (SSL) socket is used to establish the login. After that, for gem processes on the same node as their client application, communication reverts to a normal socket connection. For Gem processes that are running on a different node than their client, communication continues to use SSL.
This results in a slightly slower connection, due to the overhead of encrypting and decrypting data. To configure the gem to use normal socket communication for remote connections on secure networks, set the GEM_RPC_USE_SSL configuration option to false.
Private Page Cache
The setting for the GEM_PRIVATE_PAGE_CACHE_KB configuration option specifies the size (in KB) of the Gem’s private page cache. The default value of this option is 1000; in most cases, this value is acceptable, and you do not need to do any further tuning.
When monitoring the Gem, if the value of the statistic LocalCacheOverflowCount is non-zero, you may want to increase the setting for GEM_PRIVATE_PAGE_CACHE_KB as needed.
Native Code
By default, generation of native code for Smalltalk methods is enabled. This is configured using GEM_NATIVE_CODE_ENABLED configuration option. When native code is disabled, execution is interpreted; behavior will be identical but somewhat slower.
Native code generation can be disabled using the runtime parameter #GemNativeCodeEnabled, but it cannot then be re-enabled for that session’s lifetime.
If any breakpoints are set in any methods, native code is disabled. Native code is re-enabled when all breakpoints have been removed.
To determine if native code is in use by the currently executing session, execute:
GsProcess usingNativeCode
Under some configurations on x86, in particular on the Macintosh, the 32-bit offset limit may be exceeded in some cases with a very large temporary object cache. If this occurs, native code is disabled.
Note that the Foreign Function Interface (FFI) feature has additional limitations when native code is disabled. FFI is discussed in the Programming Guide for GemStone/S 64 Bit.
3.4 How To Access the Configuration at Run Time
GemStone provides several methods in class System that let you examine, and in certain cases modify, the session configuration parameters at run time.
To Access Current Settings at Run Time
System class methods let you examine the configuration of your current Gem session process. There are three access methods for session processes:
gemConfigurationReport
Returns a SymbolDictionary whose keys are the names of configuration file parameters, and whose values are the current settings of those parameters in the current session’s Gem process.
gemConfigurationAt: aName
Returns the value of the specified configuration parameter from the current session, or returns nil if that parameter is not applicable to a session process.
configurationAt: aName
Returns the value of the specified configuration parameter, giving preference to the current session process if the parameter applies to a Gem.
To Change Settings at Run Time
The class method System class >>configurationAt: aName put: aValue lets you change the value of the internal run-time parameters in Table 3.1, provided you have the appropriate privileges.
Parameters read from the configuration file at process startup are in all uppercase, and are read-only. Parameters that can be changed at runtime have similar, but not necessarily identical, names that are in mixed case without underscores.
CAUTION
Do not change configuration parameters unless there is a clear reason for doing so. Incorrect settings can have serious adverse effects on GemStone performance. Appendix A provides additional guidance about run-time changes to specific parameters.
The following example changes the value of the configuration option #GemFreeFrameLimit:
topaz 1> printit
System configurationAt: #GemFreeFrameLimit put: 4000
%
4000
For more information about the parameters that can be changed at run time, see Appendix A, “GemStone Configuration Options”.