10. GemBuilder Configuration Parameters
GemBuilder provides configuration settings that allow GemBuilder to operate differently for development or debugging, control details of the user interface, and tune your program for performance.
This appendix describes the GemBuilder configuration parameters, their default and legal values, and their significance.
10.1 Setting Configuration Parameters
Some configuration parameters control fundamental features of GemBuilder, and must remain the same while the image is running. Other parameters can be modified while GemBuilder is running, and may take effect immediately or at a later point, or can be set individually for a session to override the global behavior. The configuration parameter descriptions starting here provide specific details for each parameter.
Global settings
When sessions log in, they obtain an initial set of configuration parameters based on the configuration settings in the current global GbsConfiguration.
To determine the current global setting of a parameter, send the parameter name as a message to the global instance of GbsConfiguration, GbsConfiguration current. For example, the following expression returns the setting of the connectVerification parameter:
GbsConfiguration current connectVerification
false
To globally set a parameter, append a colon to the parameter name and send it as a message to the GbsConfiguration instance, with the desired value as the argument. For example, to set the connectVerification parameter, send:
GbsConfiguration current connectVerification: true
You may also use the Settings Browser to view and change the settings of these parameters. (see Settings Browser.)
Session-specific settings
While many configuration parameters apply to the image as a whole, other parameters may be modified for specific sessions.
For these parameters, the value in GbsConfiguration current is used at login. Subsequently, you may send the GbsConfiguration messages to the session's configuration (acquired by sending #configuration to the session) to determine or modify the value for that session only.
For example, if the current session requires a larger traversal buffer, an expression such as the following will increase the size for this session, while leaving the global setting for new sessions unchanged.
GBSM currentSession configuration traversalBufferSize: 500000.
10.2 GemBuilder Configuration Parameters
The following table summarizes GemBuilder configuration parameters. Each parameter is described in detail following the table.
alwaysUseGemCursor
Used to reduce the number of conditions under which GBS switches cursors. When true, GBS changes the cursor to the “gem” cursor during all interactions with the server. When false, the cursor is only changed during some server operations by the GBS tools.
autoMarkDirty
Defines whether modifications to client objects are automatically detected. When false, the application must explicitly send markDirty to a client object after it has been modified, so GemBuilder will know to update the object in GemStone. Do not change this setting while sessions are logged in from this client process.
backupPolling
The waiting socket interface normally detects events from the server without needing to poll. When backupPolling is false, polling is rare, only every 10 minutes. When backupPolling is set to true, GemBuilder will poll the server every eventPollingFrequency milliseconds, rather than waiting a full 10 minutes.
The default is false on Windows, but since the waiting interface may occasionally miss signals on Unix platforms, the default is true on other platforms.
The default is set when GBS parcels are loaded, so if you move images containing GBS between platforms, you may wish to set this option explicitly.
Default: false on Windows, true on Unix
blockingProtocolRpc
Determines whether to use blocking or nonblocking protocol for RPC sessions (linked sessions cannot be non-blocking). When false, nonblocking protocol is used, enabling other threads to execute in the image while one or more threads are waiting for a GemStone call to complete. When true, GemBuilder must wait for a GemStone call to complete before proceeding with the thread that called it. Should not be changed for sessions that are already logged in.
blockReplicationEnabled
When false, GemBuilder raises an exception when block replication is attempted; useful in determining if your application depends on block replication.
blockReplicationPolicy
Block replication requires decompiling and compiling the source code for blocks at runtime. Since it is usually not possible to include the Smalltalk compiler in a runtime image, block replication may cause problems in runtime applications. Block callbacks use client forwarders to evaluate the block in the client. Block callbacks escape the documented limitations of block replication, but do not perform well for blocks invoked repeatedly from GemStone.
Legal values: #replicate or #callback
bulkLoad
This parameter has no effect when logged into a GemStone/S 64 Bit server.
When true, newly created objects are stored in GemStone as permanent objects immediately, bypassing a step wherein they are temporary and eligible for storage reclamation by the GemStone garbage collector unless other objects refer to them (in which case they become permanent objects, as usual). Bypassing this step improves performance for bulk data loading. When false, the temporary object step is not bypassed.
clampByCallback
Specifies whether replication clamps can be applied by server class callback or not. Support for clampByCallback requires use of the callback feature in recent GemStone/S 64 Bit versions, and is intended to be implemented under the guidance of GemTalk Engineering.
clientMapCapacity
The minimum capacity in objects of the client object map. The client object map is used to map client replicates, stubs, and forwarders to their corresponding server objects. The map will grow in capacity if it runs out of room, and may shrink in capacity if it has an excess of free space. The map will never shrink its capacity below clientMapCapacity. This value is also used as the initial capacity of the map, which is initialized only upon the first login after loading GBS into a clean image. Thus, changing clientMapCapacity will only affect the initial cache size if changed before the first login after GBS load. After that time, however, changing clientMapCapacity will limit the shrinkage of the map. Growing and shrinking the map take time, so performance-critical applications that replicate many objects may wish to have a larger map capacity. Check statistics for map size and grow/shrink events to see whether your map capacity is sufficient.
The legal value is any positive Integer; GBS will set the actual capacity to an appropriate value somewhat larger than specified.
Legal values: any positive Integer.
clientMapFinalizerPriority
The process priority at which garbage-collected objects are finalized from the client object map. These must be finalized before the server can garbage-collect the corresponding server objects. By default, this finalization is done at a priority below the normal application priority. This allows finalization to run at times when the main application is waiting for user input or responses from the server. However, if your application seldom waits, and creates a lot of garbage replicates, it is possible that the finalizer might not get enough CPU cycles to keep up. If the unfinalized objects have no remaining references on the server, this will cause increased memory usage in the gem. If this is a problem, you may need to increase this setting to a priority above that of your application. Changing this value will change the finalizer's priority at the time of the next server interaction.
Legal values: an Integer between 1 and 99, inclusive
confirm
When true, you are prompted to confirm various GemBuilder actions. Leave set to true during application development; deployed applications may set to false.
connectorNilling
When true, GemBuilder nils the Smalltalk object for certain session-based connectors after logout: all name, class variable, or class instance variable connectors whose postconnect action is #updateST or #forwarder. When the last session logs out, the Smalltalk object references of global connectors are also set to nil. Fast connectors, class connectors, and connectors whose postconnect action is #updateGS or #none are not set to nil. Clearing connectors that depend on being attached to GemStone server objects helps prevent defunct stub and forwarder errors.
When false, the logout sequence leaves the state of persistent objects in the image as it was.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #connectorNilling: to the session's configuration to change the value for that session only. The session's current value will be used at logout.'
connectVerification
When true, connectors verify at login that they are not redefining a connector that already exists, and class connectors verify that the two classes they are connecting have compatible structures. When false, these things are not checked.
Connector verification can slow down the login process. Set to true during development unless logging in becomes too slow, or your connector definitions are stable. Applications in production should normally set this to false.
In addition to setting this parameter via the Settings Dialog or via message sends, the Connector Browser check box “Global verification”: sets this parameter. See Connector Browser.
defaultFaultPolicy
This parameter has no effect when logged into a GemStone/S 64 Bit server, which is always #immediate.
Specifies GemBuilder’s default approach to updating client Smalltalk objects whose GemStone counterparts have changed. When #lazy, GemBuilder responds to a change in a GemStone server object by turning its client Smalltalk replicate into a stub. The new GemStone value is faulted in the next time the stub is sent a message. When #immediate, GemBuilder responds to a change in a GemStone server object by updating the client Smalltalk replicate immediately. The defaultFaultPolicy is implemented by Object >> faultPolicy. Subclasses can override this method for specific cases.
Legal values: #immediate/#lazy
deprecationWarnings
When true, any attempt to use a deprecated feature of GemBuilder for Smalltalk causes a proceedable exception to be raised. Deprecated features may be removed in a future release. When false, deprecated features may be used with no warning.
eventPollingFrequency
How often, in milliseconds, that GemBuilder polls for GemStone events such as changed object notification or Gem-to-Gem signaling.
Legal values: any Positive Integer
eventPriority
The priority of the Smalltalk process that responds to GemStone events—that is, the priority at which the block will execute that was supplied as an argument to the keyword gemSignalAction:, notificationAction:, or signaledAbortAction:. These keywords occur in messages used by Gem-to-Gem signaling, changed object notification, or when GemStone signals you to abort so that it can reclaim storage, respectively.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #eventPriority: to the session's configuration to change the value for that session only. The priority will not change immediately, but the new value will be used the next time an action block is set and the event detection process is restarted.
Legal values: an Integer between 1and 99, inclusive
faultLevelLnk
The default number of levels to replicate an object from GemStone to client Smalltalk in a linked session.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #faultLevelLnk: to the session's configuration to change the value for that session only.
faultLevelRpc
The default number of levels to replicate an object from GemStone to client Smalltalk in a remote session.
The value in GbsConfiguration current is used at login. Subsequently, you may send #faultLevelRpc: to the session's configuration to change the value for that session only.
forwarderDebugging
When true, forwarders support debugging by responding to some basic messages locally, such as printOn:, instVarAt:, and class, which returns GbsForwarder. When false, these messages are forwarded to the GemStone server object.
freeSlotsOnStubbing
When true, stubbing an existing replicate causes all persistent named instance variables (that is, those that will be faulted in when the stub is unstubbed) and all indexable instance variables to be set to nil, allowing stubs and their potentially outdated instance variables to be garbage collected if they become eligible. When false, GemBuilder does not alter instance variable values. To override this behavior on a class-by-class basis, reimplement #freeSlotsOnStubbing (inherited from Object).
fullCompression
When true, GemStone compresses all communication between the client and the server, reducing the amount of data sent across a network connection to an RPC gem. Has no effect on linked sessions. For network connections with low throughput, compression may improve overall performance. For fast enough network connections, compression may decrease overall performance due to the CPU time required to do compression and decompression.
This setting only takes effect at the time that a library is loaded (see libraryName below). If a library is loaded you will need to save your image, quit, and restart for a new fullCompression value to take effect.
gcedObjBufferSize
The initial size in objects of the buffer that holds server object IDs for objects which have been garbage collected in the client. The buffer is enlarged when necessary, but performance-sensitive applications that release many replicates at once may want to avoid this. The IDs in this buffer are sent to the server with each server interaction.
generateClassConnectors
When true, a session connector is automatically created to connect two classes, one of which has been automatically generated in response to the presence of the other by the mechanisms described in the discussion of parameters generateClientClasses and generateServerClasses. When false, session connectors are not automatically created.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #generateClassConnectors: to the session's configuration to change the value for that session only.
See Class Mapping.
generateClientClasses
When true, if a GemStone server object is fetched into the client Smalltalk image and the client Smalltalk image does not currently define the class of which it is an instance, a corresponding class is defined in the image. When false, behavior is defined by the client Smalltalk image.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #generateClientClasses: to the session's configuration to change the value for that session only.
See Class Mapping.
generateServerClasses
When true, if a client Smalltalk object is stored into GemStone and GemStone does not currently define the class of which it is an instance, a corresponding class is defined in GemStone Smalltalk. When false, GemBuilder raises an error.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #generateServerClasses: to the session's configuration to change the value for that session only.
See Class Mapping.
InitialDirtyPoolSize
Initial size of the GbsSession dirtyPool identity set. For bulk loading, increasing this value reduces the number of times the set needs to grow. For applications that flush a small number of objects, decreasing this value (while keeping it larger than the number of objects being flushed) improves flushing performance.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #initialDirtyPoolSize: to the session's configuration to change the value for that session only. The new value will take effect after the next server operation.
Legal values: any positive Integer. GBS will select a prime size greater than this value.
libraryName
The name of the DLL or shared library to use to contact the server. If this is set to an empty string, GBS loads the first found library with a default name. It tries loading linked libraries first (which support both linked and RPC logins), then RPC-only libraries. If a libraryName is specified, that exact library name is loaded. If the library is not found, an error is reported. On Unix or Linux, the library name may be specified as an absolute file path to the library file, or as a simple name (e.g. libgcirpc.so). On Windows, use a simple name. If a simple name is used, the library is found in the (platform-specific) standard directories for libraries. This setting does not affect any library that is already loaded. If a library is already loaded you will need to save your image, quit, and restart for a new libraryName to take effect.
removeInvalidConnectors
When true and confirm is false, if a connector fails to resolve at login, it is removed from the connector collections so that the failed connector does not attempt to resolve again at the next login.
When true and confirm is true, you are prompted to remove invalid connectors during login.
When false, invalid connectors are ignored.
In addition to setting this parameter via the Settings Dialog or via message sends, the Connector Browser check box “Remove Bad Connectors”: sets this parameter. See Connector Browser.
replicateExceptions
When true and connected to a GemStone/S 64-bit 3.0 or later server, server exceptions that are not caught on the server will be replicated to the client and signaled on the client stack. This allows objects referenced from exception instance variables to also be replicated to the client.
When false, or when connected to an earlier server product or version, server errors are associated with a client error class by number.
serverMapLeafCapacity
The lower bound in objects of the capacity of each leaf in the server map. The server map maps the IDs of server objects to their corresponding client replicates, forwarders, and stubs. The server map is structured as a shallow fixed-depth tree. Each node in the tree is identified by the upper bits of the object ID. Each leaf node is a hashed collection indexed by the lower bits of the object ID. The upper limit of the capacity for each leaf depends on the server product and version, ranging from 222 to 224 object IDs. Leaves are created on demand; only those leaves that actually contain objects exist. This setting controls the initial capacity of each leaf. Leaves will grow and shrink as necessary, but will not shrink below this setting. Growing and shrinking take some time, so performance-sensitive applications may want to adjust this value. Using a larger value decreases the time spent growing and shrinking each leaf, but increases memory use, and also increases the time spent initializing each leaf.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #serverMapLeafCapacity: to the session's configuration to change the value for that session only. From that point on, new leaf creation and all leaf shrinkage will be subject to the new value.
Legal values: any positive Integer. GBS will select a prime table size greater than this value, but not exceeding 224.
stubDebugging
When true, stubs support debugging by responding to some basic messages locally, such as printOn:, instVarAt:, and class, which returns GbxObjectStub. When false, these messages cause the stub to fault into the client image from GemStone.
traversalBufferSize
Sets the size, in bytes, of the buffer used in traversal replication.
This setting can be different from session to session. The value in GbsConfiguration current is used at login. Subsequently, you may send #traversalBufferSize: to the session's configuration to change the value for that session only. An increase in size will take effect immediately, but a decrease may not.
Legal values: any positive Integer. The actual setting must be a multiple of 8, larger than 2048. If an illegal number is entered, it will be replaced with the nearest legal number.
useGbsMemoryPolicy
When true, GemBuilder will install a memory policy that defers some garbage collection activities until the current replication is finished, when more garbage is likely to be available for collection. In conditions of heavy replication, this can both control memory growth and save time running unproductive garbage collection.
When false, a normal VisualWorks MemoryPolicy is used. You may tune the GBS memory policy the same way you would a VisualWorks MemoryPolicy. Tuning parameters are preserved when changing the state of this parameter.