1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
/* -*- c++ -*- */
/*
* Copyright © 2010 Intel Corporation
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice (including the next
* paragraph) shall be included in all copies or substantial portions of the
* Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
*/
#pragma once
#ifndef IR_HIERARCHICAL_VISITOR_H
#define IR_HIERARCHICAL_VISITOR_H
/**
* Enumeration values returned by visit methods to guide processing
*/
enum ir_visitor_status {
visit_continue, /**< Continue visiting as normal. */
visit_continue_with_parent, /**< Don't visit siblings, continue w/parent. */
visit_stop /**< Stop visiting immediately. */
};
/**
* Base class of hierarchical visitors of IR instruction trees
*
* Hierarchical visitors differ from traditional visitors in a couple of
* important ways. Rather than having a single \c visit method for each
* subclass in the composite, there are three kinds of visit methods.
* Leaf-node classes have a traditional \c visit method. Internal-node
* classes have a \c visit_enter method, which is invoked just before
* processing child nodes, and a \c visit_leave method which is invoked just
* after processing child nodes.
*
* In addition, each visit method and the \c accept methods in the composite
* have a return value which guides the navigation. Any of the visit methods
* can choose to continue visiting the tree as normal (by returning \c
* visit_continue), terminate visiting any further nodes immediately (by
* returning \c visit_stop), or stop visiting sibling nodes (by returning \c
* visit_continue_with_parent).
*
* These two changes combine to allow nagivation of children to be implemented
* in the composite's \c accept method. The \c accept method for a leaf-node
* class will simply call the \c visit method, as usual, and pass its return
* value on. The \c accept method for internal-node classes will call the \c
* visit_enter method, call the \c accpet method of each child node, and,
* finally, call the \c visit_leave method. If any of these return a value
* other that \c visit_continue, the correct action must be taken.
*
* The final benefit is that the hierarchical visitor base class need not be
* abstract. Default implementations of every \c visit, \c visit_enter, and
* \c visit_leave method can be provided. By default each of these methods
* simply returns \c visit_continue. This allows a significant reduction in
* derived class code.
*
* For more information about hierarchical visitors, see:
*
* http://c2.com/cgi/wiki?HierarchicalVisitorPattern
* http://c2.com/cgi/wiki?HierarchicalVisitorDiscussion
*/
class ir_hierarchical_visitor {
public:
ir_hierarchical_visitor();
/**
* \name Visit methods for leaf-node classes
*/
/*@{*/
virtual ir_visitor_status visit(class ir_variable *);
virtual ir_visitor_status visit(class ir_constant *);
virtual ir_visitor_status visit(class ir_loop_jump *);
/**
* ir_dereference_variable isn't technically a leaf, but it is treated as a
* leaf here for a couple reasons. By not automatically visiting the one
* child ir_variable node from the ir_dereference_variable, ir_variable
* nodes can always be handled as variable declarations. Code that used
* non-hierarchical visitors had to set an "in a dereference" flag to
* determine how to handle an ir_variable. By forcing the visitor to
* handle the ir_variable within the ir_dereference_variable visitor, this
* kludge can be avoided.
*
* In addition, I can envision no use for having separate enter and leave
* methods. Anything that could be done in the enter and leave methods
* that couldn't just be done in the visit method.
*/
virtual ir_visitor_status visit(class ir_dereference_variable *);
/*@}*/
/**
* \name Visit methods for internal-node classes
*/
/*@{*/
virtual ir_visitor_status visit_enter(class ir_loop *);
virtual ir_visitor_status visit_leave(class ir_loop *);
virtual ir_visitor_status visit_enter(class ir_function_signature *);
virtual ir_visitor_status visit_leave(class ir_function_signature *);
virtual ir_visitor_status visit_enter(class ir_function *);
virtual ir_visitor_status visit_leave(class ir_function *);
virtual ir_visitor_status visit_enter(class ir_expression *);
virtual ir_visitor_status visit_leave(class ir_expression *);
virtual ir_visitor_status visit_enter(class ir_texture *);
virtual ir_visitor_status visit_leave(class ir_texture *);
virtual ir_visitor_status visit_enter(class ir_swizzle *);
virtual ir_visitor_status visit_leave(class ir_swizzle *);
virtual ir_visitor_status visit_enter(class ir_dereference_array *);
virtual ir_visitor_status visit_leave(class ir_dereference_array *);
virtual ir_visitor_status visit_enter(class ir_dereference_record *);
virtual ir_visitor_status visit_leave(class ir_dereference_record *);
virtual ir_visitor_status visit_enter(class ir_assignment *);
virtual ir_visitor_status visit_leave(class ir_assignment *);
virtual ir_visitor_status visit_enter(class ir_call *);
virtual ir_visitor_status visit_leave(class ir_call *);
virtual ir_visitor_status visit_enter(class ir_return *);
virtual ir_visitor_status visit_leave(class ir_return *);
virtual ir_visitor_status visit_enter(class ir_discard *);
virtual ir_visitor_status visit_leave(class ir_discard *);
virtual ir_visitor_status visit_enter(class ir_if *);
virtual ir_visitor_status visit_leave(class ir_if *);
/*@}*/
/**
* Utility function to process a linked list of instructions with a visitor
*/
void run(struct exec_list *instructions);
/* Some visitors may need to insert new variable declarations and
* assignments for portions of a subtree, which means they need a
* pointer to the current instruction in the stream, not just their
* node in the tree rooted at that instruction.
*
* This is implemented by visit_list_elements -- if the visitor is
* not called by it, nothing good will happen.
*/
class ir_instruction *base_ir;
/**
* Callback function that is invoked on entry to each node visited.
*
* \warning
* Visitor classes derived from \c ir_hierarchical_visitor \b may \b not
* invoke this function. This can be used, for example, to cause the
* callback to be invoked on every node type execpt one.
*/
void (*callback)(class ir_instruction *ir, void *data);
/**
* Extra data parameter passed to the per-node callback function
*/
void *data;
/**
* Currently in the LHS of an assignment?
*
* This is set and cleared by the \c ir_assignment::accept method.
*/
bool in_assignee;
};
void visit_tree(ir_instruction *ir,
void (*callback)(class ir_instruction *ir, void *data),
void *data);
ir_visitor_status visit_list_elements(ir_hierarchical_visitor *v, exec_list *l);
#endif /* IR_HIERARCHICAL_VISITOR_H */
|
