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.5.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.5.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 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 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
GcsiDetachSharedCache

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
GcsiDetachSharedCache

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