PolyML.Statistics structure

The PolyML.Statistics structure provides a way for a program to read information about the run-time system. As well as getting information about the local Poly/ML process it is also possible to get information about another Poly/ML process being run by the same user.

structure Statistics:
  sig
    val getLocalStats : unit ->
       {sizeHeap: int,
       gcFullGCs: int,
       timeGCUser: Time.time,
       threadsInML: int,
       gcPartialGCs: int,
       threadsTotal: int,
       timeGCSystem: Time.time,
       userCounters: int vector,
       threadsWaitIO: int,
       timeNonGCUser: Time.time,
       sizeAllocation: int,
       timeNonGCSystem: Time.time,
       threadsWaitMutex: int,
       threadsWaitSignal: int,
       sizeAllocationFree: int,
       sizeHeapFreeLastGC: int,
       threadsWaitCondVar: int,
       sizeHeapFreeLastFullGC: int}

    val getRemoteStats : int ->
       {sizeHeap: int,
       gcFullGCs: int,
       timeGCUser: Time.time,
       threadsInML: int,
       gcPartialGCs: int,
       threadsTotal: int,
       timeGCSystem: Time.time,
       userCounters: int vector,
       threadsWaitIO: int,
       timeNonGCUser: Time.time,
       sizeAllocation: int,
       timeNonGCSystem: Time.time,
       threadsWaitMutex: int,
       threadsWaitSignal: int,
       sizeAllocationFree: int,
       sizeHeapFreeLastGC: int,
       threadsWaitCondVar: int,
       sizeHeapFreeLastFullGC: int}

    val setUserCounter : int * int -> unit
    val numUserCounters : unit -> int
end

There are two functions that return information..

val getLocalStats : unit -> { ... }
Returns information about the Poly/ML process that has called this function.
val getRemoteStats : int -> { ... }

Returns information about another Poly/ML process. The argument is the process id (pid) of the Poly/ML process for which information is requested. Raises the Fail exception if this is not a currently running Poly/ML process or the calling user does not have permission to read the statistics. The statistics are held in shared memory and on Unix systems these are memory-mapped files in the user's .polyml directory.

The actual information returned is still being determined and may well change.

In addition to information about the run-time system the statistics mechanism provides a small array of values that can be set by the ML code. This allows an ML program to set values that can be read in another process.

val numUserCounters : unit -> int

Returns the number of counters available. Currently this is eight.

val setUserCounter : int * int -> unit

setUserCounter(n, m) stores the value m in the n-th counter.

Writing to the counters is potentially an expensive operation. If the information is likely to change rapidly it will usually be best to use a separate thread to poll the information periodically and update the counter.