2. Changes in Administration

Previous chapter

Next chapter

This chapter describes changes and new features that apply to the administration of a GemStone Repository, and changes in the GemStone environment, configuration, and tools, including:

Changes in Users and ObjectSecurityPolicies

Changes in Garbage Collection

Changes in Backup

GemStone access without a Stone / Solo sessions

Other Changes related to administrative operations

Changes in Errors

Changes in Utilities

Topaz changes

Configuration Parameter Changes

Changes in Statmonitor and Cache Statistics

2.1  Changes in Users and ObjectSecurityPolicies

Added system users

Two new users have been added, HostAgentUser and CodeLibrarianUser, each with new GsObjectSecurityPolicies. These are system users that, like other system userProfiles, are immune from password expiration.

HostAgentUser

The HostAgent processes run as the HostAgentUser. HostAgentUser’s UserGlobals contains a number of classes that implement the HostAgent’s responsibilities. These are intended for internal use by the HostAgent.

The HostAgentUser maintains security information for remote X509 caches, specifically object filtering; you should update and manage the password for this user as you do for DataCurator.

CodeLibrarianUser

The CodeLibrarianUser’s UserGlobals contains classes that support the new package management in v3.5.

All Cypress-prefixed class names have been moved into this space.

Changes in GsObjectSecurityPolicy

Names

Instances of GsObjectSecurityPolicy now know their name, and methods have been implemented, name and name:. The actual name is kept in a dynamic instance variable #_name.

Display Changes

The asString/printString display of a GsObjectSecurityPolicy has been changed to include the name. For example,

DataCuratorObjectSecurityPolicy(#2 in Repository
  SystemRepository, Owner DataCurator write, Group
  DataCuratorGroup write, World read)

Added GsObjectSecurityPolicy for object filtering

There is an additional GsObjectSecurityPolicy in this version, the ObjectFiltersSecurityPolicy. The objects in this policy are not transmitted to remote X509 caches.

These are the GsObjectSecuritiesPolicies in a new 3.5 repository, and the permissions for the recently added policies.

1 SystemObjectSecurityPolicy

2 DataCuratorObjectSecurityPolicy

3 GsTimeZoneObjectSecurityPolicy

4 SecurityDataObjectSecurityPolicy

5 GsIndexingObjectSecurityPolicy

6 PublishedObjectSecurityPolicy

7 GcUserObjectSecurityPolicy

8 NamelessObjectSecurityPolicy

9 CodeLibrarianUserObjectSecurityPolicy
Owner CodeLibrarianUser write, World read

10 HostAgentUserObjectSecurityPolicy
Owner HostAgentUser write, World read

11 ObjectFiltersSecurityPolicy
Owner DataCurator write, Group DataCuratorGroup write, World read

Note that if your repository already contains security policies with the given indices, these remain unchanged; the new GsObjectSecuritiesPolicies are added starting at the available index.

UserProfile instance variable renamed

UserProfile’s instance variable spare3, which has been in use for loginHook functionality, has been renamed to loginHook.

New authentication scheme for X509-Secured GemStone

#X509 is now one of the authentication schemes (in addition to #GemStone, #UNIX, #LDAP, and #SingleSignOn). Users with #X509 authentication may only login via X509-Secured GemStone.

However, unlike other authentication schemes, users with any authentication can also login using X509-Secure GemStone, provided they have the appropriate user certificates.

The following methods have been added to support limiting authentication for specific users to X509-secured logins.

UserProfile >> authenticationSchemeIsX509 
UserProfile >> enableX509Authentication  
UserProfile >> x509loginStatus 
UserProfile class >> newX509WithUserId:

2.2  Changes in Garbage Collection

Repository reclaimAll with wait added

Repository >> reclaimAll is usually invoked after a mark/sweep garbage collection, to ensure all garbage is reclaimed. However, reclaimAll cannot do the reclaim until several other steps are completed, including each session’s voting on possible dead. To allow reclaimAll to be invoked immediately after a mark/sweep, rather than checking for progress in the overall garbage collection sequence, a method that includes a wait has been added.

Repository >> reclaimAllWait: timeLimitSeconds
Explicitly triggers the reclamation of all shadowed objects. If the Reclaim GcGem configuration parameter #reclaimDeadEnabled is true, then it waits until the dead objects are ready to reclaim (voteStateIdle) before it starts the reclaim.

If the timeLimitSeconds value is -1, then it waits indefinitely for the reclaim to complete. This should be done with caution, as under certain conditions the session could appear to wait forever. To avoid this, make sure that other sessions are committing/aborting to allow voting on possible dead to complete.

This method signals an error if:

  • The voteState is not idle and AdminGem is not running.
  • ReclaimGem is not running.
  • The timeout expires before the reclaim completes. Explicit errors are returned to indicate whether it was waiting for voteStateIdle or the reclaim.
  • No progress is detected for 5 minutes. A warning is logged if a session takes more than 20 seconds to vote.

Setting persistent GcGem parameters

GcGem parameters for the Reclaim and Admin GcGems are set in two places:

  • The persistent location is in the GcUser’s UserGlobals, which contains parameter names and values. Logging in as GcUser and updating the values does not affect a currently running GcGem; the values take effect when the GcGem is restarted. Also, these values are not range checked until the GcGem is restarted, at which time range errors appear in the appropriate log file.
  • Transiently, using previously existing setAdminConfig... and setReclaimConfig... methods. These methods performed range checking and take effect immediately, but did not persist through GcGem restart. When the GcGem restarted, the value reverted to the persistent value in the GcUser’s UserGlobals.

To allow you to set both the persistent and transient values in a single operation, and to provide range checking for persistent settings, the following methods have been added:

System class >> setPersistentAdminConfig: configSymbol toValue: aVal
System class >> setPersistentReclaimConfig: configSymbol toValue: aVal

These methods update the value in GcUser’s UserGlobals, and update the currently used value by the appropriate GcGem, and if these operations are successful (if the values are in range and the user has appropriate privileges), commits the changes.

These methods perform an abort and will error if there are uncommitted changes in the image.

The GcUser’s UserGlobal associations remain the location of record, so there is no change required to existing code that reads or updates these settings.

Parameter descriptions

The configuration parameters and the maximum/minimum and default values for the Reclaim and Admin GcGems were previously documented by a single string at the value #defaultValues in the GcUser's UserGlobals.

Now, the Reclaim and Admin GcGem parameters, which are entirely disjoint as of recent releases, are documented by separate strings, at the key #defaultAdminConfigValues and #defaultReclaimConfigValues. These are now available when logged in as other userIds via the new methods:

System class >> adminGemConfigs
System class >> reclaimGemConfigs

This returns a string containing the details for each parameter that applies to the given GcGem. For example

'#adminVerboseLogging
Controls the amount of logging information written to the
log file.
If set to false, normal logging information will be written. 
If set to true, extra logging information is written to the
log file.
     (default: false)
 
 #epochGcMaxThreads
   MaxThreads used for next epochGc
     (default:1, min:1, max: 32)
...

GcUser’s UserGlobals no longer contains the key #defaultValues.

Reset to default

To reset the configuration values to the default:

System class >> setDefaultAdminConfigs
System class >> setDefaultReclaimConfigs

objectTableCleanupIdleTime removed

The GcUser’s UserGlobals’ entry #objectTableCleanupIdleTime is obsolete and has been removed.

maxTransactionDuration minimum reduced

The minimum value for #maxTransactionDuration was previously 10 and is now 1.

2.3  Changes in Backup

Compressed backups using lz4 have improved compression

Lz4 backups could be significant larger than the gzip version. The default lz4 file compression level has been changed from 0 to 3, reducing the resulting compressed backup size differential.

Repository >> fullBackupTo: can accept an array

When fullBackup was made multithreaded, the longest complete form (fullBackupTo:MBytes:compressKind:bufSize:) was designed to accept either a single filename or an array of filenames. The restriction of fullBackupTo: to a single file was unnecessary, and has been lifted; this method can now be used with an Array of 1 or more filenames.

restoreFromBackup: accepts filename without compression suffix

Backup files may be uncompressed, or compressed using .gz or .lz4. Previously, the compression extension was required. Now, this can be omitted. If no exact match is found for the specified backup filename, the system will look for that filename with .gz suffix, then for that filename with .lz4 suffix.

2.4  GemStone access without a Stone / Solo sessions

Using a "solo" session, you can login and perform many GemStone operations when a Stone is not running. This is designed to allow Smalltalk-based scripting, for single-user operations that do not require updating persistent state in the session’s own environment.

By default, a solo login uses the clean, empty distribution extent, and no additional setup is required to perform a topaz solo login and execute GemStone Smalltalk code.

You may also use another extent, either empty or containing application code, data or other modifications, provided the following are true for the repository extent:

The configuration parameter GEM_SOLO_EXTENT specifies the extent file to be used by a Solo session. This defaults to $GEMSTONE/bin/extent0.dbf.

From the environment of a solo session, there is no Stone. Many System class and Repository methods are disallowed in a Solo session, since they would require a connection to a Stone. This includes markForCollection, reclaimAll, and methods that make and restore backups. Attempting to execute these methods would result in an ImproperOperation Error (#2050).

Solo login from topaz

To login Solo from topaz linked or RPC, execute set solologin on, then login.

For example:

topaz> set solologin on
topaz> login
[Info]: LNK client/gem GCI levels = 35001/35001
[Info]: Read-Only Repository: /benton2/users/lalmarod/GS6435/bin/extent0.dbf
[Info]: using libicu version 58.2
[Info]: Gave this process preference for OOM killer: wrote 
to /proc/20027/oom_score_adj value 250
[03/26/2018 16:40:33.628 PDT]
  gci login: currSession 1  linked session 
successful Solo login
topaz 1> 

Values set for the Stone using set gemstone are ignored if set solologin on is set.

topaz RPC, which may have multiple sessions logged in, is not limited to all logins being either ordinary or solo logins. You have both kinds of logins within the same topaz RPC.

Object creation and memory use

Each Solo RPC or linked Gem also opens a 10MB read-write temporary file, /tmp/gemRO_<pid>_extent1.dbf, which is deleted on logout or process exit.

Object creation in a Solo session is limited to temporary object memory, but you may create objects as needed up to the limit of memory. To ensure there is sufficient memory, you may:

  • Set a larger value for GEM_TEMPOBJ_CACHE_SIZE in the configuration file used by the topaz or Gem session.
  • For linked sessions, use -T cachesize on the topaz command line.
  • For RPC sessions, include -T cachesize in the NRS gemnetid login parameter.

Solo sessions other than from topaz

Solo sessions are not limited to topaz. When the GCI flag #GCI_LOGIN_SOLO is used in the login parameters, any GCI application may create a solo login.

The following image methods are available:

GemStoneParameters >> soloLoginFlag
Used by GsExternalSession >> loginSolo; returns the bits equivalent to GCI_LOGIN_SOLO.

GsExternalSession >> loginSolo
This specifies that the external session should be logged in as a solo session, using the GEM_SOLO_EXTENT value in the config file used by the gem process for the new session, or the value passed in with the Gem NRS
'gemnetobject -C GEM_SOLO_EXTENT=extentname').

GsSession >> isSolo
Returns true if the receiver is logged in as a solo session, false otherwise.

GsSession class >> isSolo
Returns true if the current session is logged in as a solo session, false otherwise.

Scripting with topaz solo using she-bang

You may now create executable text files containing GemStone code, and execute these in a solo session at the command line. The following restrictions apply:

  • The environment variable $GEMSTONE must be set
  • she-bang scripts execute in a solo session, that is, do not log into a running stone.
  • she-bang scripts run in a linked topaz session
  • no topaz command line options can be passed in
  • No .topazini files are read

The first line of the she-bang can be defined two ways:

#!/usr/bin/env topaz
This form requires that $GEMSTONE/bin be on the machine executable search path.

#!fullPathToExecutable/topaz
This does not require topaz on the machine search path ($GEMSTONE must still be defined). fullPathToExecutable must be the full path; she-bang will not expand an environment variable.

For example, an executable text file with the following contents:

#!/usr/bin/env topaz
set u DataCurator p swordfish
login
run
  | files sz |
  files := GsFile 
	contentsOfDirectory: '$GEMSTONE/data/tranlog*.dbf'
	onClient: false.
  sz := 0.
  files do: [:ea | sz := sz + (GsFile sizeOfOnServer: ea)].
  'tranlogs consume ', (sz / 1024) asInteger asString, ' KB'.
%

Can be executed, without a running stone, to report the sum total size of tranlog files in the data directory. Topaz exits when the script completes.

2.5  Other Changes related to administrative operations

Local host reported as localhost

Some output that previously provided the complete IPv4 address and the host name that this resolved to, now return localhost when the host is the same as the Stone’s host.

For example, cases that would previously report ::ffff:204.45.141.15 and kata.gemtalksystems.com, if on the local node, now report 127.0.0.1 and localhost.

This change affects the Stone login log produced when STN_LOGIN_LOG_ENABLED is set, and element 11 of the Array returned from System class >> descriptionOfSession: , among others.

Related changes also resolve issues with using 0.0.0.0 as a logsender listening address (bug 47787)

Printing of socket addresses changed

The printing of IPv6 mapped IPv4 socket addresses to log files and the results for methods such as GsSocket >> peerAddress have been changed to remove the::ffff: prefix.

GEMSTONE_NRS_ALL and handling of NetLDI child process logs

Now, the forking of a gem or pgsvr by the NetLDI does not alter the GEMSTONE_NRS_ALL that was inherited from the NetLDI. This ensures that the directory locations specified by the NetLDI are not modified such that a remote process acquires invalid information.

The startnetldi -D option now controls the default location for child log processes, in the absence of other specifications, and is the recommended way to configure child log file directory locations. You do not need to specify the %D in the NRS for the child process for this to take effect. There are other changes in how -D is handled; see NetLDI log directory handling.

The precedence for log file locations is:

1. If there is setting for #dir in the Gem login parameters, this directory is used as the working directory and as the log files location.

2. Otherwise, if there is a setting for #dir in the GEMSTONE_NRS_ALL in the client environment, this directory is used for log files.

3. Otherwise, if there is a setting for #dir in the GEMSTONE_NRS_ALL in the environment in which the NetLDI was started, or if the startnetldi -D argument was specified, this is used for log files. Note that the NetLDI will not start with both of these specified as different locations. Like #dir, -D defines the working directory for the process as well as the log file directory.

4. Otherwise, the home directory of the unix user.

Changes in System class >> descriptionOfSession:

Change in return values for invalid or partially logged in sessions

If the session argument is not a valid session, or is partially logged in or out, descriptionOfSession: now returns nils, zeros, and empty strings rather than entirely nil elements.

Added elements

The Array returned from System class >> descriptionOfSession: has added elements:

23. The sessionId of the HostAgent session through which this session is communicating to stone, or -1 if the session is not using a HostAgent.

24. If the specified session is a HostAgent, the HostAgent’s listening port. Otherwise -1.

performOnServer: using alternate shells

The method performOnServer: by default executes using /bin/sh. It is now possible to specify that a different shell be used, using the new method:

System class >> performOnServer: aString withShell: aShellOrNil 

If aShellOrNil is nil, ’/bin/sh’ shell is used. Otherwise, the argument should be the path to a shell that will be used to process the command via the -c argument.

Korn Shell (/bin/ksh), Z Shell (/bin/zsh) and bash (/bin/bash) are known to work.

C Shell (/bin/csh) and its variants (/bin/tcsh) are known to not work.

Disconnecting from one mid-level cache and connecting to another

When there are multiple mid-level caches available to a Gem, it is now possible to cleanly disconnect from using one of them as a mid-level cache, and reconnect to a different one. This can be used with both regular and X509-secured mid level caches.

This is done using the added method:

System class >> midLevelCacheReconnect: hostName
If already connected to a mid level cache, disconnect from that cache. Then, attempt to connect to an existing mid-level cache on the specified host, using the same NetLDI name that was used to login to the stone.The session's gem process must be on a machine different from the machine running the stone process in order for this to succeed.

Determining what mid-level cache a session is connected to

The following new method allows you to confirm what node the current session is using as a mid-level cache. It returns the IP address, or nil if no mid level cache is in use.

System class >> midLevelCacheAddress

C stack traces on Windows for fatal errors

On Windows, access violation errors (e.g. SEGV) from RPC GCI will now provide a C stack for subsequent debugging. All GCI calls will handle access violations this way. The stack is written to the GCI trace file, if that is active, or to a file with the name GCI*.tmp in the windows temporary directory,

c:\users\userid\AppData\Local\Temp\

Note that the .pdb files from the GemStone Windows Client distribution must be present in order to capture a stack trace.

Handling cygwin file names on windows

When running GemStone under cygwin, path names are now automatically corrected to the windows-compatible format.

2.6  Changes in Errors

New Error Classes

CryptoError 

This is a subclass of ExternalError. It is an exception signaled when certain encrypt/decrypt methods fail.

Error number: 2756. C mnemonic: ERR_CryptoError

MigrationError 

This is a subclass of Error. It is an exception that can be signaled when a migration operation cannot be completed, with one argument: the object for which migration failed.

Error number: 2757. C mnemonic: ERR_MigrationError

Added Error Numbers associated with existing error classes

ABORT_ERR_GemAutoAbort 3007  
image symbol: #errAutoAbort class: TransactionBacklog
Gem process serviced a sigAbort while waiting for a GCI command while in #manualBegin transactionMode, and while #GemAutoServiceSigAbort is true.

ABORT_ERR_GemAutoLostOt 3008   
image symbol: #errAutoLostOt class: RepositoryViewLost
Gem process serviced a LostOt while waiting for a GCI command in #manualBegin transactionMode, and while #GemAutoServiceSigAbort is true.

ERR_CACHE_FAILURE 4097
PageCacheConnectionFailure or PageCacheSType::fatalError

ERR_SOLO_SESSION 2050    class: ImproperOperation
Operation not allowed or supported in a Solo session. Args: (1) details (a String)

GS_ERR_HA_TRANSPORT 4018
Transport layer error between a gem and a HostAgent thread

GS_ERR_SEM_FAILURE 4017
Semaphore failure during shared memory communication to stone

RT_ERR_BREAK_FROM_STONE 6020
Break, used from stopHostAgent OOB

Changes in Error message arguments

Error 2025 #repErrCantCreateFile, has an additional argument; certain extent add operations, such as adding an extent on an NFS-mounted drive when NFS is disallowed, will now return more error details.

Error 2160 #rtErrSelectiveAbort, now is used for multiple error conditions and an additional argument is used to hold the error condition.

The printing for Transaction error 2407 / rtErrObjIsNp (object cannot be committed) has been updated to include the OOP of the object.

2.7  Changes in Utilities

startnetldi

-t option no longer implemented

The startnetldi -t timeout argument is no longer implemented.

NetLDI log directory handling

If the -D argument to startnetldi, and the #dir specified in a the NetLDI’s GEMSTONE_NRS_ALL environment variable, are both set to specify explicit paths and are different, then startup is disallowed.

If neither the NRS of an incoming request, nor the NetLDI’s GEMSTONE_NRS_ALL environment variable, contain a #dir, and if startnetldi -D is specified, the NetLDI will use the value of the -D argument, rather than the child's home directory, for the working directory of the child process and the location in which to place child process log file.

copydbf changes

The copydbf utility does not make certificate-based connections.

The copydbf -p option has been removed. This was used to specify pageservers for remote copydbf; with modern network connections, it was no longer useful to support copydbf operations using page servers.

pageaudit additional statistics

pageaudit, in addition to reporting if there are any errors found in the page allocation with a repository, also reports statistics about the repository pages. This information is written to the pageaudit log file, tmpstnname-pageAudit.log.

The additional lines of information include:

OT Internal Pages                0.05 Mbytes          3 pages
OT Leaf Pages                    0.81 Mbytes         52 pages
Empty OT leaf pages              0.00 Mbytes          0 pages
Empty data pages                 0.00 Mbytes          0 pages
Data pages with 25%+ free        5.94 Mbytes        380 pages
Data pages with 50%+ free        4.05 Mbytes        259 pages
Free space in data pages         4.25 Mbytes     272.25 pages

gemnetobject arguments and documentation

The gemnetobject script, and related scripts gemnetdebug, gemnetobject_slow, gemnetobject_noop, and gemnetobject_keeplog, now have better documented arguments. The -h output has been updated and expanded, a man page added for gemnetobject, and gemnetobject is described in the System Administration Guide, Appendix B, with the other utilities.

In addition to the existing arguments, you may include additional arguments, with or without a leading dash and letter, at the end or within the known arguments. Unrecognized arguments and tokens are passed along to the gem and ignored.

The -U argument has been specifically added to allow passing in arbitrary strings; this ensures that future changes to the gemnetobject arguments will continue to support -U.

Note that minimal error checking is done; you should verify that your arguments were entered correctly by examining the gem log file.

All gemnetobject arguments are passed to the gem and available by System class >> commandLineArguments.

startlogsender/startlogreceiver

Hot standby change in arguments for startlogsender

The way master tranlog directories are specified for startlogsender has changed in this release. The -s stoneName and -T tranLogDir arguments are now mutually exclusive, so most hotstandby configurations will require update.

This change streamlines the process of specifying the tranlog directories, and allows configurations to be setup such that new tranlog directories can be added at runtime.

With this change, there are two disjoint ways to specify the set of tranlog directories that will be used by the logsender:

  • Explicitly provide a list of up to 20 directories using the startlogsender -T argument.
  • Using the startlogsender -s argument to specify the Stone. The Stone’s transaction log directories (specified by STN_TRAN_LOG_DIRECTORIES) will be used as the set of tranlogs used by the logsender. New transaction logs can be added at runtime (using Repository >> addTransactionLog:size:), and will be automatically picked up by the logsender.

There are no changes in the logreceiver, which accepts tranlog records from the logsender as in previous releases.

The maximum number of STN_TRAN_LOG_DIRECTORIES is now 100; this includes both tranlog directories defined in configuration files and those added at runtime.

logsender and logreceiver stats for block ID

Currently, the logsender and logreceiver can record, in statmonitor data, only the tranlog file being processed. Now the block ID is recorded in SessionStat00 in logsender, and SessionStat23 in logreceiver. (#47685)

New utility largememorypages

In previous releases, specialized commands to a pgsvr shell were required to compute the number of large/huge memory pages to configure on Linux or AIX. The pgsvr shell is no longer usable for this purpose in v3.5. Now, this information can be computed using the new utility largememorypages.

largememorypages computes the number of large or huge memory pages that will be required for a given shared page cache size and other system requirements, using a UNIX-standard command line interface.

Large or huge memory pages are available for use with GemStone on Linux and AIX. On Linux, GemStone supports 2MB and 1024MB (1GB) large pages. On AIX, 16MB large memory pages are supported. Large pages are not supported on other platforms.

Three arguments are required to do the computation: the SPC size or number of pages, the number of processes, and the number of shared counters. The memory large page size is optional and only applies on Linux. Arguments can be provided by settings in a configuration file or using command line arguments. Command line arguments have precedence over settings in the configuration file.

Usage: largememorypages [-e path ] [-z path] [-F cacheFrames | -M cacheKB]
[-P maxProcesses] [-C maxSharedCounters] [-p largeMemoryPageSize]
where:

-e path
specifies an executable config file (same as startstone -e).

-z path
specifies a system config file (same as startstone -z).

If a config file is not specified, then -M or -F and -P and -C are required.

-F cacheFrames
shared cache size expressed in 16 KB frames

-M cacheKB
shared cache size with a optional units suffix.

-P maxProcesses
setting for SHR_PAGE_CACHE_NUM_PROCS

-C maxSharedCounters
setting for SHR_PAGE_CACHE_NUM_SHARED_COUNTERS.

-p largeMemoryPageSize
large memory page size. Not allowed on AIX, which always uses 16MB. Optional on Linux, which defaults to 2MB. May be used to specify 1GB page size on Linux. Overrides setting for SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB.

For example, on Linux, using the default GemStone configuration file:

unix> largememorypages -e $GEMSTONE/bin/initial.config
Cache config is 4736 pages = 74 MB,  total is 122 MB,  overhead
64% of configured size
Large page size requested is: 2 MB.
Large page overhead: 1.16 MB
For 4687 pages, 52 processes and 1900 shared counters, 
0 pusherThreads
  required cache size is 127926272 bytes.
Number of 2 MB large pages required: 61
... <further instructions for update>

For more information, refer to the Installation Guide for Linux and for AIX.

gslist no longer distributed on Windows

The gslist utility was previously included in the distribution on Windows, but was of minor value since no GemStone server processes can run on Windows. It is no longer included in the Windows distribution.

startstone and startnetldi return codes

Previously, if startnetldi or startstone detected a netldid/stoned that was already running, it returned status 0; while a startup failure returns status 3, HOST_EXIT_ERR.

Now, if these processes detect an already running process, they will return status 2, HOST_EXIT_WARNING.

2.8  Topaz changes

New command line argument -S for scripting

The topaz -S filename command line argument allows you to pass in a topaz script, similar to the -I option. The difference is that -I is intended for initialization, and suppresses all output (until the first error), while -S only suppresses topaz echo output. In combination with -q, which suppressed topaz environment output, a topaz script now can have complete control over the output display.

Output is stops being suppressed after the first error, or failed expecterror or expectresult, for error diagnosis. If the topaz has an interactive shell, processing also stops, to allow debugging.

Improvements for support for additional compilation environments

Topaz commands are all now environment aware. A number of commands have been updated to correctly handle environments over envId 0 (the default GemStone environment). The changes include both bug fixes, new behavior, and specific definitions for behavior that was previously unclear.

If you are using environments > 0, refer to the topaz help text for the individual commands for specific defined behavior.

In addition, executing the ENV command with no argument now prints the current environmentId.

X509-Secure GemStone login arguments

The login parameters for X509-Secured GemStone are a disjoint set from the standard login parameters. SET has the following added options to specify the X509-secured login parameters. If any of these are set, the standard login parameter fields are cleared, and vice versa.

NETLDI:   LOGFILE:   KEY:   EXTRAGEMARGS:    DIRECTORY:   CACERT:   CERT:

For details, see the GemStone/S 64 Bit X509-Secured GemStone System Administration Guide.

BREAK accepts new method specification syntax

The BREAK command now accepts class >> method syntax,

className [class] [(implementingSuperclassName)] >> methodName

If a class implementingSuperclassName is specified in parenthesis after the className, implementingSuperclassName is used for lookup, not className.

For example:

topaz 1> break Delay >> wait
topaz 1> break SmallInteger class (Integer) >> fromStream: @4

topaz objectSpec parsing numbers

Previously, object specs in the form of integers did not accept some reasonable inputs, for example base 16 notation. Now, these cases may use values that can be resolved as Integers using Number>>fromString:. (#47537)

List classes allows subset filtering

The topaz command list classes lists all classes in all SymbolDictionaries. You may now specify by substring and only display classes with names that include that substring (case insensitive). For example,

topaz 1> list classes cert
GsX509Certificate
GsX509CertificateChain

Omitting deprecated methods from method lists

The topaz display and omit commands have added the deprecated subcommand. This controls whether topaz commands that return lists of methods include or omit deprecated methods. By default, deprecated methods are included.

Deprecated methods are those that send one of the following messages:

deprecated
deprecated: 
deprecatedNotification:

For example, the method concurrencyMode is deprecated:

topaz 1> implementors concurrencyMode
System class >> concurrencyMode
topaz 1> omit deprecated
topaz 1> implementors concurrencyMode
(Omitted 1 deprecated methods)

Added topaz commands

POLLFORSIGNAL

The command POLLFORSIGNAL has been added, to support interactive testing of the GciPollForSignal code. This command causes topaz to wait for out-of-band activity from the Gem processing, using GciPollForSignal. It can be interrupted by control-C.

TMETHOD to support code management

The code management subsystem under development uses a distinct Smalltalk method format. The new topaz command tmethod compiles a method that is formatted in this way. Code packaging is in active development and all functionality is subject to change.

Subcommands added to topaz SET

ENABLEREMOVEALL

SET ENABLEREMOVEALL ON | OFF controls whether topaz REMOVEALLMETHODS and REMOVEALLCLASSMETHOD commands are enabled or ignored. The default is ON, allowing all methods to be removed.

INPUTPAUSEONERROR

SET INPUTPAUSEONERROR ON | OFF allows topaz processing to pause if an error occurs while executing an INPUT command, making it easier to locate source file errors.

SOLOLOGIN

SET SOLOLOGIN ON | OFF controls topaz solo login. When set solologin is on, subsequent logins will be solo logins, that is, logins without a Stone. For details, see GemStone access without a Stone / Solo sessions.

ENVVAR

Used to set an environment variable within the environment of the topaz process. Requires two arguments, which will be interpreted as Strings. The word ENVVAR cannot be abbreviated.

For example:

topaz 1> set envvar foo abc

Subcommands added to OMIT and DISPLAY

VERSIONEDCLASSNAMES

When display versionedclassnames is set, which is the default, topaz includes [verionNumber] following the class name, for instances of classes that are not the last one in the classHistory of that class. This is limited to when display oops is also set. omit versionedclassnames causes this version detail to be not displayed.

Subcommand added to topaz STACK

TERMINATE

STACK TERMINATE sends #terminate to the GsProcess of the current stack, if the stack is not owned by the scheduler.

2.9  Configuration Parameter Changes

Parsing and Error handling for configuration files

The way configuration files are parsed has been reworked in this release.

  • Syntax errors in configuration settings may now be treated as fatal errors, where in previous releases they were warnings, with the value ignored and defaults used.
  • For some parameters, such as SHR_PAGE_CACHE_PERMISSIONS, an out of range value is now a fatal error, where previously it was a warning.
  • Some configuration parameters that are not relevant for the specific process are not printed in the process log header.
  • Some obsolete configuration values that were previously printed in log headers are now completely removed.

Determining which Configuration files are in use

GemStone supports both system and executable Configuration files for both Gem and Stone. To determine the existence and names of these files, the following methods have been added:

System class >> stoneConfigurationFileNames
System class >> gemConfigurationFileNames

Each will return a dictionary with two keys, #GEMSTONE_SYS_CONF and #GEMSTONE_EXE_CONF, pointing to the full, expanded path and name of the system and executable configuration files, respectively, or nil if no file was specified or found.

Added runtime-only configuration parameters

The configuration parameters GemConfigFileNames and StnConfigFileNames returns the names of the gem and system configuration files for the Gem and Stone, respectively. These are accessed using expression such as System gemConfigurationAt: #GemConfigFileNames and System stoneConfigurationAt: #StnConfigFileNames.

Added keys in results of gem/stoneConfigurationReport

The result of System class >> gemConfigurationReport now includes the key GemConfigFileNames, and the result of System class >> stoneConfigurationReport includes the key StnConfigFileNames.

Each points to 2-element array containing system configuration file name or an empty string, and the executable configuration file name or an empty string.

Removed Configuration Parameters

The following configuration parameters are not used in v3.5, and have removed. A warning is issued if they are included in a configuration file.

GEM_PRIVATE_PAGE_CACHE_KB

STN_PRIVATE_PAGE_CACHE_KB

Changes in existing configuration parameters

STN_COMMITS_ASYNC disabled

Testing encountered a case in which with this configuration parameter set to true, a record was missing from the transaction log during restore after the Stone ran out of tranlog disk space. (#48098) To avoid risk, this parameter has been disabled in v3.5.

STN_TRAN_LOG_DIRECTORIES limited to 100

The maximum number of entries in STN_TRAN_LOG_DIRECTORIES is now 100.

SHR_PAGE_CACHE_SIZE_KB rounded to up next MB increment

The calculation of the size of the shared page cache is based on SHR_PAGE_CACHE_SIZE_KB and on other parameters that compute overhead. The SHR_PAGE_CACHE_SIZE_KB value is converted to pages; the number of pages is now rounded up to the next 1 MB increment in size.

SHR_PAGE_CACHE_NUM_PROCS provides additional count

The computation of SHR_PAGE_CACHE_NUM_PROCS based on STN_MAX_SESSIONS now provides one additional session to support threads in the ReclaimGem.

DBF_ALLOCATION_MODE

If a list of values is used, the values should be in the range 5..200; values under 5 are disallowed for efficiency, and values up to 200 are now allowed.

GEM_PGSVR_COMPRESS_PAGE_TRANSFERS, GEM_PGSVR_UPDATE_CACHE_ON_READ, STN_PAGE_MGR_COMPRESSION_ENABLED

The default for these parameters was previously false, and is now true.

GEM_TEMPOBJ_MESPACE_SIZE and GEM_TEMPOBJ_POMGEN_SIZE

Previously, the maximum value was 1GB, now the maximum is 2GB.

STN_LOG_IO_FLAGS

This previously documented as Solaris only, but can be used in Linux environments.

GEM_TEMPOBJ_POMGEN_SIZE scaling

The size of the POM Generation memory space can be set explicitly using the configuration parameter GEM_TEMPOBJ_POMGEN_SIZE, but is normally derived from the GEM_TEMPOBJ_CACHE_SIZE setting.

Previously, the calculation of the default was linear, setting the POM gen space to about 0.8 times (80%) of the TOC size. For very large temporary object caches, this is larger than is useful. Now, the multiplier used is based on the size of the TOC, using interpolation on the line defined by these values:

TOC size

Multiplier

<= 200MB

0.8

600MB

0.6

1GB

0.27

5GB

0.15

>5GB

0.1

Added Configuration Parameters

GEM_SOLO_EXTENT

Specifies an extent to be used for Gem session without a Stone. For details, see GemStone access without a Stone / Solo sessions.

STN_ANONYMOUS_SSL

If true, all connections between the Stone and other processes are encrypted using anonymous SSL. Does not apply to X509-secured processes. For details, see Loading a specific OpenSSL library version.

Added runtime-only configuration parameters

DelayAutoServiceSigAbort

Runtime-only configuration option, applicable only in a session in which System class >> clientIsRemote returns true. Affects operation of GemAutoServiceSigAbort configuration option.

DelayAutoServiceSigAbort can be used to set an internal delay counter to a specified value, the delivery of the error 3007 will be delayed for the specified number of GCI calls received by the gem; this is to facilitate testing.
Runtime name: #DelayAutoServiceSigAbort
Default value zero, min 0, max 16r7FFFFFFF.

GemAutoServiceSigAbort

Runtime-only config option, applicable only in a session in which System class >> clientIsRemote returns true. When the session's transaction mode is autoBegin or transactionless the gem process will automatically service any sigAbort received when there is no GCI traversal in progress and the gem is waiting for the next GCI command. After auto servicing of one or more sigAbort, the next GCI command will signal a TransactionBacklog with error number 3007.

After auto servicing of a sigAbort, the "GciAlteredObjs" portion of the traversal result of the next GciStoreTravDoTravRefs will include the result of writeSetUnion of commits by other sessions since last GciStoreTravDoTravRefs intersected with the PureExportSet.
Runtime name: #GemAutoServiceSigAbort
Default value: false

GemCommitConflictDetails

Runtime-only config option for the gem.When true, System class >> conflictsReport and System class >> transactionConflicts return details about which session(s) caused commit conflicts. Must be enabled by System gemConfigurationAt: #GemCommitConflictDetails put: true, before the conflicting commit.
Runtime name: #GemCommitConflictDetails
Default value: false

GemConfigFileNames

Runtime read-only configuration parameter, which returns the names of the system and executable configuration files for the Gem.

System gemConfigurationAt: #GemConfigFileNames 

Returns an Array:

{ systemConfigFileName . exeConfigFileName }

StnConfigFileNames

Runtime read-only configuration parameter, which returns the names of the system and executable configuration files for the Stone.

System stoneConfigurationAt: #StnConfigFileNames

Returns an Array:

{ systemConfigFileName . exeConfigFileName }

Added X509-only Configuration Parameters

The following configuration parameters have been added to support X509-Secured GemStone. These configuration parameters are all intended to be used in the configuration file passed with the -E argument to startnetldi that is started on a remote or mid-level node, and have no effect otherwise. For details, see the GemStone/S 64 Bit X509-Secured GemStone System Administration Guide.

GemRemoteCommit

If TRUE, an X509-secured remote gem will execute the critical region of commit in the session's thread in the pgsvr or HostAgent on stone host. Only applies, and is the default, if the gem host and the stone host have same byte order.

NETLDI_HostAgentUser_cert

Specifies the HostAgentUser’s public key cert file for a mid-level cache node or for cache warming.

NETLDI_HostAgentUser_key

Specifies the HostAgentUser’s private key file for a mid-level cache node or for cache warming.

NETLDI_PORT_RANGE

Optional, specifies a port range for listening sockets in forked X509-secured Gems processes.

NETLDI_START_MIDCACHE

If true, indicates that the node will be acting as a mid-level cache.

NETLDI_WARMER_ARGS

Sets arguments to cache warming for an X509-secured mid or leaf cache. Arguments are -n int to specify the number of threads, -d to warm data as well as object table pages, and -M midCacheHostName to warm from a running mid-level cache on another node.

SHR_PUSH_TO_MIDCACHES_THREADS

Specifies the number of threads to use to push changed pages committed by X509-secured Gems, from the Stone’s cache to the mid caches.

2.10  Changes in Statmonitor and Cache Statistics

Statmonitor automatic delete of older data files

You can now configure statmonitor with automatic new file creation to automatically delete older files. Using the -K numFiles flag to statmonitor, you can specify the number of older files to save (not including the file currently being updated). You may only use -K with either -r or -R.

Removed statistics

The following statistics have been removed:

LocalCacheAllocatedPceCount

LocalCacheFreeFrameCount

LocalCacheFreePceCount

LocalCacheOverflowCount

LocalCachePceCountLimit

LocalCachePceReclaimCount

LocalCacheStalePcesRemovedCount

LocalCacheValidPcesRemovedCount

NumCacheWarmers

ServiceMs

SpinLockFreeFrameSleepCount

SpinLockFreePceSleepCount

StnMessagesNeedWakeUpCount

StnMessagesNoWakeUpCount

Changed statistics

WaitMs now reports the average number of milliseconds to service an I/O, including both time spent in the I/O queue and time performing the I/O. Previously this only included the queue time.

Added statistics

The following are now reported for Pgsvrs as well as for Gems:

DepMapKeysChanged

GemHasCommitToken

TimeProcessingCommit

TimeStoneCommit

TimeWaitingForCommit

The following cache statistics have been added:

ClientPageReadsCommit (Pgsvr)
Pages read by the HostAgent thread during commit.

MessagesToStoneCommit (Pgsvr)
The number of messages sent from a session to the stone during critical region of commit.

PagePushListFullCount (Stone)
Number of times a commit on stone host could not find a free entry in the page push list.

PoorlyFilledPagesCount (Gem)
Number of poorly filled data pages committed by this gem. This statistic is only updated during a commit.

PriorityPagesNeedReclaimSize (Stone)
The number of poorly filled pages that are pending, that is, the backlog waiting for the ReclaimGem reclaim task.

PusherDroppedNewLife (Pgsvr)
Pages in the page push list that had a new lifetime in stone's cache by the time the pusher thread processed that page in the list.

PusherDroppedNotInCache (Pgsvr)
Pages in the page push list that were no longer in stone's cache by the time the pusher thread processed that page in the list.

PusherDroppedPoorFill (Pgsvr)
Poorly filled data pages in the page push list that were skipped by a page pusher thread.

PusherSentPages (Pgsvr)
Pages sent to a mid cache by a page pusher thread in a HostAgent on the stone host.

ReadWaitMs (HardDisk)
The average number of milliseconds to service a read I/O, including both time spent in the I/O queue and time performing the read.

ReceivedPages (Pgsvr)
Pages received by a page receiver thread in a mid cache HostAgent.

ReceivedPagesAlreadyInCache (Pgsvr)
Pages received by a page receiver thread and ignored because the were already in the mid cache, or because a read of the page was in progress.

ReceivedPagesCacheFull (Pgsvr)
Pages received by a page receiver thread and ignored because the mid cache was full.

ReceivedPagesReadInProgress (Pgsvr)
Pages received by a page receiver thread and ignored because a read of that page was in progress.

TempOopsAllocated (All)
TempOopsAllocated is the number of oops allocated to a session, but not yet committed.

TempPagesAllocated (All)
TempPagesAllocated is the number of pages allocated to a session, but not yet committed.

WriteWaitMs (HardDisk)
The average number of milliseconds to service a write I/O, including both time spent in the I/O queue and time performing the write.

Mac System and Host Stats added

Statmonitor now collecting host stats on Mac

Previously, as Mac OS system statistics were not available, statmonitor on the Mac did not include arguments controlling the collection of process and system statistics.

Statmonitor on the Mac now supports the flags -Q, -U, -X, and -Y.

Added Per-Process System Statistics

ContextSwitches
The number of times this thread has lost the CPU to another thread. Thread switches can occur either inside of a single process or across processes. A thread switch may be caused either by one thread asking another for information, or by a thread being preempted by another, higher priority thread becoming ready to run.

CopyOnWriteFaults
The total number of times a private copy of a shared page needed to be made due to a write to the shared page.

MsgRecv
The number of messages received by the process.

MsgSent
The number of messages sent by the process.

PageFaults
The total number of Page Faults by the threads executing in this process. A page fault occurs when a thread refers to a virtual memory page that is not in its working set in main memory. This will not cause the page to be fetched from disk if it is on the standby list and hence already in main memory, or if it is in use by another process with whom the page is shared.

PageIns
The total number of times pages have been brought into memory from disk by the operating system's memory manager.

ReadKBytes
The total number of kilobytes read from the operating system I/O device.

SystemCalls
The total number of system calls.

SysTime
The number of milliseconds the process has been using the CPU to execute system calls.

ThreadCount
Number of threads currently active in this process. An instruction is the basic unit of execution in a processor, and a thread is the object that executes instructions. Every running process has at least one thread.

ThreadsRunningCount
The number of threads owned by the process that are executing on the CPU.

UserTime
The number of milliseconds the process has been using the CPU to execute user code.

WriteKBytes
The total number of kilobytes written to the operating system I/O device.

Added Mac OS Host Statistics

ActiveFileMemoryKB
The amount of memory used for buffering files that has been used recently.

CopyOnWritePageFaults
Number of copy on write page faults.

CPUs
The number of online CPUs on the local machine.

ExternalPageCount
Number of memory pages that are file-backed (non-swap).

FreeMemoryKB
The number of kilobytes of memory in the free list.

InactiveFileMemoryKB
The amount of memory used for buffering files that has not been used recently.

InternalPageCount
Number of memory pages that are anonymous.

LoadAverage1
The average number of threads ready to run over the last one minute.

LoadAverage5
The average number of threads ready to run over the last five minutes.

LoadAverage15
The average number of threads ready to run over the last fifteen minutes.

PageCacheHits
Number of Cocoa object cache hits.

PageCacheLookups
Number of Cocoa object cache lookups.

PageFaults
The total number of Page Faults by the threads executing in this process. A page fault occurs when a thread refers to a virtual memory page that is not in its working set in main memory. This will not cause the page to be fetched from disk if it is on the standby list and hence already in main memory, or if it is in use by another process with whom the page is shared.

PagesCompressed
Number of pages which have been compressed.

PagesDecompressed
Number of pages which have been decompressed.

PagesPagedIn
The total number of pages that have been brought into memory from disk by the operating system's memory manager.

PagesPagedOut
The total number of pages that have been flushed from memory to disk by the operating system's memory manager.

PagesPurged
Number of pages which have been purged.

PagesSwappedIn
The total number of swapped out pages that have been brought back into memory from disk.

PagesSwappedOut
The total number of pages that have been moved from memory to disk due to a swap out operation.

PercentCpuActive
The percentage of the total available time that has been used to execute user or system code.

PercentCpuIdle
The percentage of the total available time that has been spent sleeping.

PercentCpuSystem
The percentage of the total available time that has been used to execute system (i.e. kernel) code.

PercentCpuUser
The percentage of the total available time that has been used to execute user code.

PhysicalMemoryKB
The amount of physical memory on the machine in kilobytes.

Processes
The number of processes in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. Each process represents the running of a program.

PurgablePagesCount
Number of purgable memory pages in use.

ReactivatedPages
Number of memory pages that have been reactivated.

SpeculativePagesCount
Number of memory pages holding data that was read speculatively from disk but has not yet been accessed.

ThrottledPageCount
Number of throttled pages.

UnevictableMemoryKB
The amount of memory that cannot be swapped.

ZeroFilledPages
The total number of pages have been block-cleared to contain all zeros.

Previous chapter

Next chapter