Package com.singularsys.jep.misc

# Class MonitoringEvaluator

java.lang.Object
com.singularsys.jep.standard.FastEvaluator
com.singularsys.jep.misc.MonitoringEvaluator

All Implemented Interfaces:
  `Evaluator`, `GenericVisitor<Object,Void,EvaluationException>`, `JepComponent`, `Serializable`

public class MonitoringEvaluator extends FastEvaluator
A subclass of FastEvaluator that monitors the number of times each function, operator, variable, and constant is called during evaluation. It can be configured to record the time spent in each call. The time for each function is measured from the the time the `visitFun(Node)` method is called to the time it returns. The instance time is the time spent minus the times for each child.

Since:
  Jep 4.1
See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `class`
  `MonitoringEvaluator.CountAndTime`
  A class to hold the count and times of function/operator/variable/constant calls.
  `static interface`
  `MonitoringEvaluator.GetWithException<T>`
  Functional interface for functions to be measured.
  `static enum`
  `MonitoringEvaluator.Type`
  The type of monitoring to perform.

- ## Field Summary

  ### Fields inherited from class com.singularsys.jep.standard.FastEvaluator

  `trapInfinity, trapNaN, trapNullValues, trapUnsetValues`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MonitoringEvaluator(MonitoringEvaluator.Type measureTime)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clears the call counts for functions, operators, variables, and constants.
  `Object`
  `evaluate(Node node)`
  Main entry point, evaluates a node and returns and object with the value of the node.
  `String`
  `formatTabbedTable(String str)`
  `String`
  `getCallTable()`
  `String`
  `getCallTree()`
  `Map<String,MonitoringEvaluator.CountAndTime>`
  `getConstantCallCounts()`
  Returns a map of constant values to the number of times they were called during evaluation.
  `Map<String,MonitoringEvaluator.CountAndTime>`
  `getFunctionCallCounts()`
  Returns a map of function names to the number of times they were called during evaluation.
  `JepComponent`
  `getLightWeightInstance()`
  Gets a light-weight instance suitable for using in multiple threads.
  `int`
  `getMaxDepth()`
  Returns the maximum depth of the evaluation tree during evaluation.
  `Map<Node,MonitoringEvaluator.CountAndTime>`
  `getNodeCallCounts()`
  Returns a map of nodes to the number of times they were called during evaluation.
  `int`
  `getNumCalls()`
  `Map<String,MonitoringEvaluator.CountAndTime>`
  `getOperatorCallCounts()`
  Returns a map of operator names to the number of times they were called during evaluation.
  `long`
  `getTotalInstanceTime()`
  Returns the total instance time spent in all function/operator/variable/constant calls during evaluation.
  `Map<String,MonitoringEvaluator.CountAndTime>`
  `getVariableCallCounts()`
  Returns a map of variable names to the number of times they were called during evaluation.
  `void`
  `init(Jep jep)`
  Initialize the component.
  `String`
  `justifiedCallTable()`
  Print the call table sizing columns to fit
  `String`
  `justifiedCallTree()`
  Print the call tree sizing columns to fit
  `Object`
  `measure(String name, Node node, MonitoringEvaluator.GetWithException<Object> sup)`
  Measure the time spent executing the supplied function.
  `Object`
  `visitConstant(Node node)`
  `protected Object`
  `visitFun(Node node)`
  Visits a function/operator node.
  `Object`
  `visitVar(Node node)`

  ### Methods inherited from class com.singularsys.jep.standard.FastEvaluator

  `eval, isTrapInfinity, isTrapNaN, isTrapNullValues, isTrapUnsetValues, makeException, nodeAccept, setTrapInfinity, setTrapNaN, setTrapNullValues, setTrapUnsetValues, visit, visit, visit, visit`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface com.singularsys.jep.Evaluator

  `eval`

  ### Methods inherited from interface com.singularsys.jep.GenericVisitor

  `makeException, visit, visitChildren`

- ## Constructor Details

  - ### MonitoringEvaluator

    public MonitoringEvaluator(MonitoringEvaluator.Type measureTime)
    Constructor. Measuring time can slow down the evaluation by half.
    Parameters:
      `measureTime` - one of `MonitoringEvaluator.Type.MEASURE_TIME` or `MonitoringEvaluator.Type.DO_NOT_MEASURE_TIME`

- ## Method Details

  - ### formatTabbedTable

    public String formatTabbedTable(String str)

  - ### evaluate

    public Object evaluate(Node node) throws EvaluationException
    Description copied from interface: `Evaluator`
    Main entry point, evaluates a node and returns and object with the value of the node.
    Specified by:
      `evaluate` in interface `Evaluator`
    Overrides:
      `evaluate` in class `FastEvaluator`
    Parameters:
      `node` - node to evaluate
    Returns:
      value after evaluation
    Throws:
      `EvaluationException` - if errors occur during evaluation;

  - ### init

    public void init(Jep jep)
    Description copied from interface: `JepComponent`
    Initialize the component. This method is called whenever a component is added to Jep. Hence, it allows components to keep track of the other components they may rely on.
    Specified by:
      `init` in interface `JepComponent`
    Overrides:
      `init` in class `FastEvaluator`
    Parameters:
      `jep` - the current Jep instance

  - ### getLightWeightInstance

    public JepComponent getLightWeightInstance()
    Description copied from interface: `JepComponent`
    Gets a light-weight instance suitable for using in multiple threads.
    Specified by:
      `getLightWeightInstance` in interface `JepComponent`
    Overrides:
      `getLightWeightInstance` in class `FastEvaluator`
    Returns:
      a new FastEvaluator

  - ### getFunctionCallCounts

    public Map<String,MonitoringEvaluator.CountAndTime> getFunctionCallCounts()
    Returns a map of function names to the number of times they were called during evaluation.
    Returns:
      a map where keys are function names and values record counts and times.

  - ### getOperatorCallCounts

    public Map<String,MonitoringEvaluator.CountAndTime> getOperatorCallCounts()
    Returns a map of operator names to the number of times they were called during evaluation.
    Returns:
      a map where keys are operator names and values record counts and times.

  - ### getVariableCallCounts

    public Map<String,MonitoringEvaluator.CountAndTime> getVariableCallCounts()
    Returns a map of variable names to the number of times they were called during evaluation.
    Returns:
      a map where keys are variable names and values record counts and times.

  - ### getConstantCallCounts

    public Map<String,MonitoringEvaluator.CountAndTime> getConstantCallCounts()
    Returns a map of constant values to the number of times they were called during evaluation.
    Returns:
      a map where keys are constant values and values record counts and times.

  - ### getNodeCallCounts

    public Map<Node,MonitoringEvaluator.CountAndTime> getNodeCallCounts()
    Returns a map of nodes to the number of times they were called during evaluation.
    Returns:
      a map where keys are nodes and values record counts and times.

  - ### clear

    public void clear()
    Clears the call counts for functions, operators, variables, and constants.

  - ### getCallTable

    public String getCallTable()

  - ### justifiedCallTable

    public String justifiedCallTable()
    Print the call table sizing columns to fit
    Returns:

  - ### justifiedCallTree

    public String justifiedCallTree()
    Print the call tree sizing columns to fit
    Returns:

  - ### visitConstant

    public Object visitConstant(Node node) throws EvaluationException
    Overrides:
      `visitConstant` in class `FastEvaluator`
    Throws:
      `EvaluationException`

  - ### visitVar

    public Object visitVar(Node node) throws EvaluationException
    Overrides:
      `visitVar` in class `FastEvaluator`
    Throws:
      `EvaluationException`

  - ### visitFun

    protected Object visitFun(Node node) throws EvaluationException
    Description copied from class: `FastEvaluator`
    Visits a function/operator node. This is the most visited method for most expression evaluations. Keeping it fast is important.
    Overrides:
      `visitFun` in class `FastEvaluator`
    Parameters:
      `node` -
    Throws:
      `EvaluationException`

  - ### measure

    public Object measure(String name, Node node, MonitoringEvaluator.GetWithException<Object> sup) throws EvaluationException
    Measure the time spent executing the supplied function. Useful when execution happens via a different path that might not otherwise be recorded.

        MonitoringEvaluator mev = new MonitoringEvaluator();
        Object value = mev.measure("calcValue", ()-> calcValue()); // the function to be measured

    Parameters:
      `name` - the name of the function to record results under
      `node` - the node to record results for
      `sup` - the function to execute, typically `() -> calcValue()`
    Returns:
      the result of executing the supplied function
    Throws:
      `EvaluationException`

  - ### getNumCalls

    public int getNumCalls()

  - ### getTotalInstanceTime

    public long getTotalInstanceTime()
    Returns the total instance time spent in all function/operator/variable/constant calls during evaluation. This will be slightly less than the total time spent in evaluation.
    Returns:

  - ### getMaxDepth

    public int getMaxDepth()
    Returns the maximum depth of the evaluation tree during evaluation.
    Returns:
      the maximum depth of the evaluation tree

  - ### getCallTree

    public String getCallTree()