1 /* 2 * Copyright (c) 2012-2017 The ANTLR Project. All rights reserved. 3 * Use of this file is governed by the BSD 3-clause license that 4 * can be found in the LICENSE.txt file in the project root. 5 */ 6 7 package org.antlr.v4.runtime.atn; 8 9 import java.util.ArrayList; 10 import java.util.List; 11 12 /** 13 * This class contains profiling gathered for a particular decision. 14 * 15 * <p> 16 * Parsing performance in ANTLR 4 is heavily influenced by both static factors 17 * (e.g. the form of the rules in the grammar) and dynamic factors (e.g. the 18 * choice of input and the state of the DFA cache at the time profiling 19 * operations are started). For best results, gather and use aggregate 20 * statistics from a large sample of inputs representing the inputs expected in 21 * production before using the results to make changes in the grammar.</p> 22 * 23 * @since 4.3 24 */ 25 public class DecisionInfo { 26 /** 27 * The decision number, which is an index into {@link ATN#decisionToState}. 28 */ 29 public final int decision; 30 31 /** 32 * The total number of times {@link ParserATNSimulator#adaptivePredict} was 33 * invoked for this decision. 34 */ 35 public long invocations; 36 37 /** 38 * The total time spent in {@link ParserATNSimulator#adaptivePredict} for 39 * this decision, in nanoseconds. 40 * 41 * <p> 42 * The value of this field contains the sum of differential results obtained 43 * by {@link System#nanoTime()}, and is not adjusted to compensate for JIT 44 * and/or garbage collection overhead. For best accuracy, use a modern JVM 45 * implementation that provides precise results from 46 * {@link System#nanoTime()}, and perform profiling in a separate process 47 * which is warmed up by parsing the input prior to profiling. If desired, 48 * call {@link ATNSimulator#clearDFA} to reset the DFA cache to its initial 49 * state before starting the profiling measurement pass.</p> 50 */ 51 public long timeInPrediction; 52 53 /** 54 * The sum of the lookahead required for SLL prediction for this decision. 55 * Note that SLL prediction is used before LL prediction for performance 56 * reasons even when {@link PredictionMode#LL} or 57 * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} is used. 58 */ 59 public long SLL_TotalLook; 60 61 /** 62 * Gets the minimum lookahead required for any single SLL prediction to 63 * complete for this decision, by reaching a unique prediction, reaching an 64 * SLL conflict state, or encountering a syntax error. 65 */ 66 public long SLL_MinLook; 67 68 /** 69 * Gets the maximum lookahead required for any single SLL prediction to 70 * complete for this decision, by reaching a unique prediction, reaching an 71 * SLL conflict state, or encountering a syntax error. 72 */ 73 public long SLL_MaxLook; 74 75 /** 76 * Gets the {@link LookaheadEventInfo} associated with the event where the 77 * {@link #SLL_MaxLook} value was set. 78 */ 79 public LookaheadEventInfo SLL_MaxLookEvent; 80 81 /** 82 * The sum of the lookahead required for LL prediction for this decision. 83 * Note that LL prediction is only used when SLL prediction reaches a 84 * conflict state. 85 */ 86 public long LL_TotalLook; 87 88 /** 89 * Gets the minimum lookahead required for any single LL prediction to 90 * complete for this decision. An LL prediction completes when the algorithm 91 * reaches a unique prediction, a conflict state (for 92 * {@link PredictionMode#LL}, an ambiguity state (for 93 * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION}, or a syntax error. 94 */ 95 public long LL_MinLook; 96 97 /** 98 * Gets the maximum lookahead required for any single LL prediction to 99 * complete for this decision. An LL prediction completes when the algorithm 100 * reaches a unique prediction, a conflict state (for 101 * {@link PredictionMode#LL}, an ambiguity state (for 102 * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION}, or a syntax error. 103 */ 104 public long LL_MaxLook; 105 106 /** 107 * Gets the {@link LookaheadEventInfo} associated with the event where the 108 * {@link #LL_MaxLook} value was set. 109 */ 110 public LookaheadEventInfo LL_MaxLookEvent; 111 112 /** 113 * A collection of {@link ContextSensitivityInfo} instances describing the 114 * context sensitivities encountered during LL prediction for this decision. 115 * 116 * @see ContextSensitivityInfo 117 */ 118 public final List<ContextSensitivityInfo> contextSensitivities = new ArrayList<ContextSensitivityInfo>(); 119 120 /** 121 * A collection of {@link ErrorInfo} instances describing the parse errors 122 * identified during calls to {@link ParserATNSimulator#adaptivePredict} for 123 * this decision. 124 * 125 * @see ErrorInfo 126 */ 127 public final List<ErrorInfo> errors = new ArrayList<ErrorInfo>(); 128 129 /** 130 * A collection of {@link AmbiguityInfo} instances describing the 131 * ambiguities encountered during LL prediction for this decision. 132 * 133 * @see AmbiguityInfo 134 */ 135 public final List<AmbiguityInfo> ambiguities = new ArrayList<AmbiguityInfo>(); 136 137 /** 138 * A collection of {@link PredicateEvalInfo} instances describing the 139 * results of evaluating individual predicates during prediction for this 140 * decision. 141 * 142 * @see PredicateEvalInfo 143 */ 144 public final List<PredicateEvalInfo> predicateEvals = new ArrayList<PredicateEvalInfo>(); 145 146 /** 147 * The total number of ATN transitions required during SLL prediction for 148 * this decision. An ATN transition is determined by the number of times the 149 * DFA does not contain an edge that is required for prediction, resulting 150 * in on-the-fly computation of that edge. 151 * 152 * <p> 153 * If DFA caching of SLL transitions is employed by the implementation, ATN 154 * computation may cache the computed edge for efficient lookup during 155 * future parsing of this decision. Otherwise, the SLL parsing algorithm 156 * will use ATN transitions exclusively.</p> 157 * 158 * @see #SLL_ATNTransitions 159 * @see ParserATNSimulator#computeTargetState 160 * @see LexerATNSimulator#computeTargetState 161 */ 162 public long SLL_ATNTransitions; 163 164 /** 165 * The total number of DFA transitions required during SLL prediction for 166 * this decision. 167 * 168 * <p>If the ATN simulator implementation does not use DFA caching for SLL 169 * transitions, this value will be 0.</p> 170 * 171 * @see ParserATNSimulator#getExistingTargetState 172 * @see LexerATNSimulator#getExistingTargetState 173 */ 174 public long SLL_DFATransitions; 175 176 /** 177 * Gets the total number of times SLL prediction completed in a conflict 178 * state, resulting in fallback to LL prediction. 179 * 180 * <p>Note that this value is not related to whether or not 181 * {@link PredictionMode#SLL} may be used successfully with a particular 182 * grammar. If the ambiguity resolution algorithm applied to the SLL 183 * conflicts for this decision produce the same result as LL prediction for 184 * this decision, {@link PredictionMode#SLL} would produce the same overall 185 * parsing result as {@link PredictionMode#LL}.</p> 186 */ 187 public long LL_Fallback; 188 189 /** 190 * The total number of ATN transitions required during LL prediction for 191 * this decision. An ATN transition is determined by the number of times the 192 * DFA does not contain an edge that is required for prediction, resulting 193 * in on-the-fly computation of that edge. 194 * 195 * <p> 196 * If DFA caching of LL transitions is employed by the implementation, ATN 197 * computation may cache the computed edge for efficient lookup during 198 * future parsing of this decision. Otherwise, the LL parsing algorithm will 199 * use ATN transitions exclusively.</p> 200 * 201 * @see #LL_DFATransitions 202 * @see ParserATNSimulator#computeTargetState 203 * @see LexerATNSimulator#computeTargetState 204 */ 205 public long LL_ATNTransitions; 206 207 /** 208 * The total number of DFA transitions required during LL prediction for 209 * this decision. 210 * 211 * <p>If the ATN simulator implementation does not use DFA caching for LL 212 * transitions, this value will be 0.</p> 213 * 214 * @see ParserATNSimulator#getExistingTargetState 215 * @see LexerATNSimulator#getExistingTargetState 216 */ 217 public long LL_DFATransitions; 218 219 /** 220 * Constructs a new instance of the {@link DecisionInfo} class to contain 221 * statistics for a particular decision. 222 * 223 * @param decision The decision number 224 */ DecisionInfo(int decision)225 public DecisionInfo(int decision) { 226 this.decision = decision; 227 } 228 229 @Override toString()230 public String toString() { 231 return "{" + 232 "decision=" + decision + 233 ", contextSensitivities=" + contextSensitivities.size() + 234 ", errors=" + errors.size() + 235 ", ambiguities=" + ambiguities.size() + 236 ", SLL_lookahead=" + SLL_TotalLook + 237 ", SLL_ATNTransitions=" + SLL_ATNTransitions + 238 ", SLL_DFATransitions=" + SLL_DFATransitions + 239 ", LL_Fallback=" + LL_Fallback + 240 ", LL_lookahead=" + LL_TotalLook + 241 ", LL_ATNTransitions=" + LL_ATNTransitions + 242 '}'; 243 } 244 } 245