The PolyML.Statistics structure

## 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.