GemStone C Statistics Interface
This appendix describes the GemStone C Statistics Interface (GCSI), a library of functions that allow your C application to collect GemStone statistics directly from the shared page cache without starting a database session.
A.1 Developing a GCSI Application
The command lines in this appendix assume that you have set the GEMSTONE environment variable to your GemStone installation directory.
Required Header Files
The GCSI Shared Library
GemStone provides a shared library, $GEMSTONE/lib/libgcsi-3.3.0-64.so, that your program will load at runtime.
- Make sure that $GEMSTONE/lib is included in your LD_LIBRARY_PATH environment variable, so that the runtime loader can find the GCSI library. For example:
export LD_LIBRARY_PATH=$GEMSTONE/lib:$LD_LIBRARY_PATH
Compiling and Linking
The $GEMSTONE/examples directory includes the sample GCSI program gsstat.cc, along with a set of sample makefiles that show how to compile the sample GCSI program, using the compilers that are used to build the GemStone product.
NOTE
It may still be possible to build your program with another compiler, as long as you specify the appropriate flags to enable multi-threading.
Whenever you upgrade to a new GemStone version, you must re-compile and re-link all your GCSI programs. This is because the internal structure of the shared cache may change from version to version. Assuming you’ve created a makefile, all you should need to do is change $GEMSTONE and rebuild.
Connecting to the Shared Page Cache
The GCSI library allows your program to connect to a single GemStone shared page cache. Once the connection is made, a thread is started to monitor the cache and disconnect from it if the cache monitor process dies. This thread is needed to prevent your program from "holding on" to the shared cache after all other processes have detached from it. In this way, your program can safely sleep for a long time without preventing the operating system from freeing and recycling shared memory should the Stone be unexpectedly shut down.
The Sample Program
The sample program gsstat.cc (in $GEMSTONE/examples) monitors a running GemStone repository by printing out a set of statistics at a regular interval that you specify. The program prints the following statistics:
- Sess — TotalSessionsCount; the total number of sessions currently logged in to the system.
- CR — CommitRecordCount; the number of outstanding commit records that are currently being maintained by the system.
- PNR — PagesNeedReclaimSize; the amount of reclamation work that is pending, that is, the backlog waiting for the GcGem reclaim task.
- PD — PossibleDeadSize; the number of objects previously marked as dereferenced in the repository, but for which sessions currently in a transaction might have created a reference in their object space.
- DNR — DeadNotReclaimedSize; the number of objects that have been determined to be dead (current sessions have indicated they do not have a reference to these objects) but have not yet been reclaimed.
- FP — The number of free pages in the Stone.
- OCS — OldestCrSession; the session ID of the session referencing the oldest commit record. Prints 0 if the oldest commit record is not referenced by any session, or if there is only one commit record.
- FF — FreeFrameCount; the number of unused page frames in the shared page cache.
To invoke gsstat, supply the name of a running Stone (or shared page cache, if running on a Gem server) and a time interval in seconds. For example:
% gsstat myStone 2
To stop the gsstat program and detach from the cache, issue a CTRL-C.
A.2 GCSI Data Types
The following C types are used by GCSI functions. The file shrpcstats.ht defines each of the GCSI types (shown in capital letters below). That file is in the $GEMSTONE/include directory.
|
The union of all four statistics structured types: shared page cache monitor, page server, Stone, and Gem. |
|
|
Common statistics collected for all processes attached to the shared cache. |
The Structure for Representing the GCSI Function Result
The structured type GcsiResultSType provides a C representation of the result of executing a GCSI function. This structure contains the following fields:
typedef struct {
signed int processId;
signed int sessionId;
ShrPcCommonStatSType cmn;
union ShrPcStatUnion u;
} ShrPcStatsSType;
class GcsiResultSType {
public:
char vsdName[SHRPC_PROC_NAME_SIZE + 1];
unsigned int statType;
ShrPcStatsSType stats;
};
In addition, a set of C mnemonics support representation of the count of each process-specific structured type:
#define COMMON_STAT_COUNT
(sizeof(ShrPcCommonStatSType)/sizeof(int))
#define SHRPC_STAT_COUNT
(sizeof(ShrPcMonStatSType)/sizeof(int) + COMMON_STAT_COUNT)
#define GEM_STAT_COUNT
(sizeof(ShrPcGemStatSType)/sizeof(int) + COMMON_STAT_COUNT)
#define PGSVR_STAT_COUNT
(sizeof(ShrPcPgsvrStatSType)/sizeof(int) + COMMON_STAT_COUNT)
#define STN_STAT_COUNT
(sizeof(ShrPcStnStatSType)/sizeof(int) + COMMON_STAT_COUNT)
GcsiAllStatsForMask
Get all cache statistics for a specified set of processes.
Arguments
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiAttachSharedCache
Attach to the specified shared page cache.
Arguments
|
Full name of the shared page cache, in the format stoneName@stoneHostIpAddress. To determine the full name of the shared cache, use the gslist -x utility. |
|
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiAttachSharedCacheForStone
Attaches this process to the specified shared page cache.
Syntax
int GcsiAttachSharedCacheForStone(
const char * stoneName,
char * errBuf,
size_t errBufSize);
Arguments
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
Description
This function assumes that the cache name is <stoneName>@<thisIpAddress> where thisIpAddress is the IP address of the local machine. This function may fail if the host is multi-homed (has more than one network interface). In that case, use GcsiAttachSharedCache to specify the full name of the shared cache.
GcsiDetachSharedCache
Detach from the shared page cache.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiFetchMaxProcessesInCache
Return the maximum number of processes that can be attached to this shared cache at any instant. The result may be used to allocate memory for a calls to the GcsiFetchStatsForAll* family of functions.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForGemSessionId
Get the cache statistics for the given Gem session id.
Arguments
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForGemSessionWithName
Get the cache statistics for the first Gem in the cache with the given cache name.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForPgsvrSessionId
Get the cache statistics for the given page server with the given session id. Remote Gems have page servers on the Stone’s cache that assume the same session ID as the remote Gem.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForProcessId
Get the cache statistics for the given process ID.
Arguments
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForShrPcMon
Get the cache statistics for the shared page cache monitor process for this shared page cache.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.
GcsiStatsForStone
Get the cache statistics for the Stone if there is a Stone attached to this shared page cache.
Return Value
Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.