1 /*
2  * [The "BSD license"]
3  *  Copyright (c) 2014 Terence Parr
4  *  Copyright (c) 2014 Sam Harwell
5  *  All rights reserved.
6  *
7  *  Redistribution and use in source and binary forms, with or without
8  *  modification, are permitted provided that the following conditions
9  *  are met:
10  *
11  *  1. Redistributions of source code must retain the above copyright
12  *     notice, this list of conditions and the following disclaimer.
13  *  2. Redistributions in binary form must reproduce the above copyright
14  *     notice, this list of conditions and the following disclaimer in the
15  *     documentation and/or other materials provided with the distribution.
16  *  3. The name of the author may not be used to endorse or promote products
17  *     derived from this software without specific prior written permission.
18  *
19  *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20  *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21  *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22  *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24  *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28  *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 module antlr.v4.runtime.atn.DecisionInfo;
32 
33 import std.conv;
34 import antlr.v4.runtime.atn.LookaheadEventInfo;
35 import antlr.v4.runtime.atn.ContextSensitivityInfo;
36 import antlr.v4.runtime.atn.AmbiguityInfo;
37 import antlr.v4.runtime.atn.ErrorInfo;
38 import antlr.v4.runtime.atn.PredicateEvalInfo;
39 
40 /**
41  * This class contains profiling gathered for a particular decision.
42  *
43  * <p>
44  * Parsing performance in ANTLR 4 is heavily influenced by both static factors
45  * (e.g. the form of the rules in the grammar) and dynamic factors (e.g. the
46  * choice of input and the state of the DFA cache at the time profiling
47  * operations are started). For best results, gather and use aggregate
48  * statistics from a large sample of inputs representing the inputs expected in
49  * production before using the results to make changes in the grammar.</p>
50  *
51  * @since 4.3
52  */
53 class DecisionInfo
54 {
55 
56     /**
57      * @uml
58      * The decision number, which is an index into {@link ATN#decisionToState}.
59      */
60     public int decision;
61 
62     public long invocations;
63 
64     /**
65      * The total time spent in {@link ParserATNSimulator#adaptivePredict} for
66      * this decision, in nanoseconds.
67      *
68      * <p>
69      * The value of this field contains the sum of differential results obtained
70      * by {@link System#nanoTime()}, and is not adjusted to compensate for JIT
71      * and/or garbage collection overhead. For best accuracy, use a modern JVM
72      * implementation that provides precise results from
73      * {@link System#nanoTime()}, and perform profiling in a separate process
74      * which is warmed up by parsing the input prior to profiling. If desired,
75      * call {@link ATNSimulator#clearDFA} to reset the DFA cache to its initial
76      * state before starting the profiling measurement pass.</p>
77      */
78     public long timeInPrediction;
79 
80     /**
81      * The sum of the lookahead required for SLL prediction for this decision.
82      * Note that SLL prediction is used before LL prediction for performance
83      * reasons even when {@link PredictionMode#LL} or
84      * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} is used.
85      */
86     public long SLL_TotalLook;
87 
88     /**
89      * Gets the minimum lookahead required for any single SLL prediction to
90      * complete for this decision, by reaching a unique prediction, reaching an
91      * SLL conflict state, or encountering a syntax error.
92      */
93     public long SLL_MinLook;
94 
95     /**
96      * Gets the maximum lookahead required for any single SLL prediction to
97      * complete for this decision, by reaching a unique prediction, reaching an
98      * SLL conflict state, or encountering a syntax error.
99      */
100     public long SLL_MaxLook;
101 
102     /**
103      * Gets the {@link LookaheadEventInfo} associated with the event where the
104      * {@link #SLL_MaxLook} value was set.
105      */
106     public LookaheadEventInfo SLL_MaxLookEvent;
107 
108     /**
109      * The sum of the lookahead required for LL prediction for this decision.
110      * Note that LL prediction is only used when SLL prediction reaches a
111      * conflict state.
112      */
113     public long LL_TotalLook;
114 
115     /**
116      * Gets the minimum lookahead required for any single LL prediction to
117      * complete for this decision. An LL prediction completes when the algorithm
118      * reaches a unique prediction, a conflict state (for
119      * {@link PredictionMode#LL}, an ambiguity state (for
120      * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION}, or a syntax error.
121      */
122     public long LL_MinLook;
123 
124     /**
125      * Gets the maximum lookahead required for any single LL prediction to
126      * complete for this decision. An LL prediction completes when the algorithm
127      * reaches a unique prediction, a conflict state (for
128      * {@link PredictionMode#LL}, an ambiguity state (for
129      * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION}, or a syntax error.
130      */
131     public long LL_MaxLook;
132 
133     public LookaheadEventInfo LL_MaxLookEvent;
134 
135     public ContextSensitivityInfo[] contextSensitivities;
136 
137     public ErrorInfo[] errors;
138 
139     public AmbiguityInfo[] ambiguities;
140 
141     public PredicateEvalInfo[] predicateEvals;
142 
143     /**
144      * The total number of ATN transitions required during SLL prediction for
145      * this decision. An ATN transition is determined by the number of times the
146      * DFA does not contain an edge that is required for prediction, resulting
147      * in on-the-fly computation of that edge.
148      *
149      * <p>
150      * If DFA caching of SLL transitions is employed by the implementation, ATN
151      * computation may cache the computed edge for efficient lookup during
152      * future parsing of this decision. Otherwise, the SLL parsing algorithm
153      * will use ATN transitions exclusively.</p>
154      *
155      * @see #SLL_ATNTransitions
156      * @see ParserATNSimulator#computeTargetState
157      * @see LexerATNSimulator#computeTargetState
158      */
159     public long SLL_ATNTransitions;
160 
161     /**
162      * The total number of DFA transitions required during SLL prediction for
163      * this decision.
164      *
165      * <p>If the ATN simulator implementation does not use DFA caching for SLL
166      * transitions, this value will be 0.</p>
167      *
168      * @see ParserATNSimulator#getExistingTargetState
169      * @see LexerATNSimulator#getExistingTargetState
170      */
171     public long SLL_DFATransitions;
172 
173     /**
174      * Gets the total number of times SLL prediction completed in a conflict
175      * state, resulting in fallback to LL prediction.
176      *
177      * <p>Note that this value is not related to whether or not
178      * {@link PredictionMode#SLL} may be used successfully with a particular
179      * grammar. If the ambiguity resolution algorithm applied to the SLL
180      * conflicts for this decision produce the same result as LL prediction for
181      * this decision, {@link PredictionMode#SLL} would produce the same overall
182      * parsing result as {@link PredictionMode#LL}.</p>
183      */
184     public long LL_Fallback;
185 
186     /**
187      * The total number of ATN transitions required during LL prediction for
188      * this decision. An ATN transition is determined by the number of times the
189      * DFA does not contain an edge that is required for prediction, resulting
190      * in on-the-fly computation of that edge.
191      *
192      * <p>
193      * If DFA caching of LL transitions is employed by the implementation, ATN
194      * computation may cache the computed edge for efficient lookup during
195      * future parsing of this decision. Otherwise, the LL parsing algorithm will
196      * use ATN transitions exclusively.</p>
197      *
198      * @see #LL_DFATransitions
199      * @see ParserATNSimulator#computeTargetState
200      * @see LexerATNSimulator#computeTargetState
201      */
202     public long LL_ATNTransitions;
203 
204     /**
205      * The total number of DFA transitions required during LL prediction for
206      * this decision.
207      *
208      * <p>If the ATN simulator implementation does not use DFA caching for LL
209      * transitions, this value will be 0.</p>
210      *
211      * @see ParserATNSimulator#getExistingTargetState
212      * @see LexerATNSimulator#getExistingTargetState
213      */
214     public long LL_DFATransitions;
215 
216     /**
217      * Constructs a new instance of the {@link DecisionInfo} class to contain
218      * statistics for a particular decision.
219      *
220      * @param decision The decision number
221      */
222     public this(int decision)
223     {
224 	this.decision = decision;
225     }
226 
227     /**
228      * @uml
229      * @override
230      */
231     public override string toString()
232     {
233 	return "{" ~
234             "decision=" ~ to!string(decision) ~
235             ", contextSensitivities=" ~ to!string(contextSensitivities.length) ~
236             ", errors=" ~ to!string(errors.length) ~
237             ", ambiguities=" ~ to!string(ambiguities.length) ~
238             ", SLL_lookahead=" ~ to!string(SLL_TotalLook) ~
239             ", SLL_ATNTransitions=" ~ to!string(SLL_ATNTransitions) ~
240             ", SLL_DFATransitions=" ~ to!string(SLL_DFATransitions) ~
241             ", LL_Fallback=" ~ to!string(LL_Fallback) ~
242             ", LL_lookahead=" ~ to!string(LL_TotalLook) ~
243             ", LL_ATNTransitions=" ~ to!string(LL_ATNTransitions) ~
244             '}';
245     }
246 
247 }
248 
249 unittest
250 {
251     auto decisionInfo = new DecisionInfo(0);
252 }