8. GemStone C Statistics Interface

Required Header Files

Your GCSI program must include the following header files:

• $GEMSTONE/include/shrpcstats.ht — Defines all cache statistics. (For a list of cache statistics, refer to the “Monitoring GemStone” chapter of the System Administration Guide for GemStone/S 64 Bit.)
• $GEMSTONE/include/gcsi.hf — Prototypes for all GCSI functions.
• $GEMSTONE/include/gcsierr.ht — GCSI error numbers.

Your program must define a main() function somewhere.

The GCSI Shared Library

GemStone provides a shared library, $GEMSTONE/lib/libgcsi-3.6.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

• $GEMSTONE/lib/libgcsi-3.6.0-64.so is a multi-threaded library, so your program must also be compiled and linked as a multi-threaded program.

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.

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)

Syntax

int GcsiAllGemStatsForGemKindRange(
int gemKindMin,
int gemKindMax,
GcsiResultSType*result,
int *resultSize
);

Arguments

gemKindMin	Minimum value of gemKind to match to.
gemKindMax	Maximum value of gemKind to match to; must be equal or greater than gemKindMin.
result	Address of an array of kind GcsiResultSType where statistics will be stored. NULL means return only a count of how many gems match.
resultSize	Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of gems whose gemKind was in this range, inclusive. If result is not NULL, this is also the number of valid elements in the result array..

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

Syntax

int GcsiAllStatsForMask(
unsigned int mask;
GcsiResultSType * result;
int * resultSize);

Arguments

mask	Indicates what types of processes to collect statistics for.
result	Address of an array of kind GcsiResultSType where statistics will be stored.
resultSize	Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of that were stored into result. Indicates the maximum number of processes for which statistics can be returned.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

Example

Mask bits should be set by a bitwise OR of the desired process types. For example, to get statistics for the stone and Shared Page Cache Monitor:

	unsigned int mask = SHRPC_MONITOR | SHRPC_STONE;

Syntax

int GcsiAllGemStatsForRegExName(
const char *regexString,
BoolType ignoreCase,
GcsiResultSType*result,
int *resultSize
char *errBuf,
size_t errBufSize
);

Arguments

regexString	A valid regular expression string. This string will be used to match against the cache name of every gem attached to the shared page cache.
ignoreCase	TRUE causes the regex search to ignore case.
result	Address of an array of kind GcsiResultSType where statistics will be stored. NULL means return only a count of how many gems match.
resultSize	Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of gems whose cache name match. If result is not NULL, this is also the number of valid elements in the result array.
errBuf	A buffer that will contain a string describing an error.
errBufSize	Size (in bytes) of errBuf.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors. Examine errBuf for an error message.

Syntax

int GcsiAttachSharedCache(
const char * fullCacheName;
char * errBuf;
size_t errBufSize);

Arguments

fullCacheName	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.
errBuf	A buffer that will contain a string describing an error.
errBufSize	Size (in bytes) of errBuf.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiAttachSharedCacheForStone
GcsiCacheIsAlive

Syntax

int GcsiAttachSharedCacheForStone(
const char * stoneName,
char * errBuf,
size_t errBufSize);

Arguments

stoneName	Name of the Stone process.
errBuf	A buffer that will contain a string describing an error.
errBufSize	Size (in bytes) of errBuf.

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.

See Also

GcsiAttachSharedCache
GcsiCacheIsAlive

Syntax

int GcsiCacheIsAlive (void);

Return Value

Returns 1 if the cache is alive and we are attached; return 0 if the cache has died, or we are not or no longer attached.

Syntax

int GcsiDetachSharedCache (void);

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiAttachSharedCache
GcsiAttachSharedCacheForStone

Syntax

int GcsiFetchMaxProcessesInCache(
int * maxProcesses);

Arguments

maxProcesses

The maximum number of processes that can be attached to this shared cache at any instant.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

Syntax

void GcsiInit(void);

 

Syntax

int GcsiStatsForGemSessionId(
int sessionId;
GcsiResultSType * result);

Arguments

sessionId	Session ID of the Gem for which statistics are requested.
result	Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

Syntax

int GcsiStatsForGemSessionWithName(
char * gemName;
GcsiResultSType * result);

Arguments

gemName	The case-sensitive name of the Gem for which statistics are requested.
result	Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

Syntax

int GcsiStatsForPgsvrSessionId(
int sessionId;
GcsiResultSType * result);

Arguments

sessionId	Session ID of the page server for which statistics are requested.
result	Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

Syntax

int GcsiStatsForProcessId(
int pid;
GcsiResultSType * result;

Arguments

pid	Process ID for which statistics are requested.
result	Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForShrPcMon
GcsiStatsForStone

Syntax

int GcsiStatsForShrPcMon(
GcsiResultSType * result);

Arguments

result

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForStone

Syntax

int GcsiStatsForStone(
GcsiResultSType * result);

Arguments

result

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon