comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java @ 22433:7f3fbd797e39

More Javadoc for FrameDescriptor
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Thu, 03 Dec 2015 19:20:09 +0100
parents 079cd9183128
children c11ce7d2e2c3
comparison
equal deleted inserted replaced
22432:079cd9183128 22433:7f3fbd797e39
85 @Deprecated 85 @Deprecated
86 public static FrameDescriptor create(Object defaultValue) { 86 public static FrameDescriptor create(Object defaultValue) {
87 return new FrameDescriptor(defaultValue); 87 return new FrameDescriptor(defaultValue);
88 } 88 }
89 89
90 /**
91 * Adds frame slot. Delegates to
92 * {@link #addFrameSlot(java.lang.Object, java.lang.Object, com.oracle.truffle.api.frame.FrameSlotKind)
93 * addFrameSlot}(identifier, <code>null</code>, {@link FrameSlotKind#Illegal}). This is slow
94 * operation that switches to interpreter mode.
95 *
96 * @param identifier key for the slot
97 * @return the newly created slot
98 */
90 public FrameSlot addFrameSlot(Object identifier) { 99 public FrameSlot addFrameSlot(Object identifier) {
91 return addFrameSlot(identifier, null, FrameSlotKind.Illegal); 100 return addFrameSlot(identifier, null, FrameSlotKind.Illegal);
92 } 101 }
93 102
103 /**
104 * Adds frame slot. Delegates to
105 * {@link #addFrameSlot(java.lang.Object, java.lang.Object, com.oracle.truffle.api.frame.FrameSlotKind)
106 * addFrameSlot}(identifier, <code>null</code>, <code>kind</code>). This is slow operation that
107 * switches to interpreter mode.
108 *
109 * @param identifier key for the slot
110 * @param kind the kind of the new slot
111 * @return the newly created slot
112 */
94 public FrameSlot addFrameSlot(Object identifier, FrameSlotKind kind) { 113 public FrameSlot addFrameSlot(Object identifier, FrameSlotKind kind) {
95 return addFrameSlot(identifier, null, kind); 114 return addFrameSlot(identifier, null, kind);
96 } 115 }
97 116
117 /**
118 * Adds new frame slot to {@link #getSlots()} list. This is slow operation that switches to
119 * interpreter mode.
120 *
121 * @param identifier key for the slot - it needs proper {@link #equals(java.lang.Object)} and
122 * {@link Object#hashCode()} implementations
123 * @param info additional {@link FrameSlot#getInfo() information for the slot}
124 * @param kind the kind of the new slot
125 * @return the newly created slot
126 */
98 public FrameSlot addFrameSlot(Object identifier, Object info, FrameSlotKind kind) { 127 public FrameSlot addFrameSlot(Object identifier, Object info, FrameSlotKind kind) {
99 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations."); 128 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations.");
100 assert !identifierToSlotMap.containsKey(identifier); 129 assert !identifierToSlotMap.containsKey(identifier);
101 FrameSlot slot = new FrameSlot(this, identifier, info, slots.size(), kind); 130 FrameSlot slot = new FrameSlot(this, identifier, info, slots.size(), kind);
102 slots.add(slot); 131 slots.add(slot);
104 updateVersion(); 133 updateVersion();
105 invalidateNotInFrameAssumption(identifier); 134 invalidateNotInFrameAssumption(identifier);
106 return slot; 135 return slot;
107 } 136 }
108 137
138 /**
139 * Finds an existing slot. This is slow operation.
140 *
141 * @param identifier the key of the slot to search for
142 * @return the slot or <code>null</code>
143 */
109 public FrameSlot findFrameSlot(Object identifier) { 144 public FrameSlot findFrameSlot(Object identifier) {
110 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations."); 145 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations.");
111 return identifierToSlotMap.get(identifier); 146 return identifierToSlotMap.get(identifier);
112 } 147 }
113 148
149 /**
150 * Finds an existing slot or creates new one. This is slow operation.
151 *
152 * @param identifier the key of the slot to search for
153 * @return the slot
154 */
114 public FrameSlot findOrAddFrameSlot(Object identifier) { 155 public FrameSlot findOrAddFrameSlot(Object identifier) {
115 FrameSlot result = findFrameSlot(identifier); 156 FrameSlot result = findFrameSlot(identifier);
116 if (result != null) { 157 if (result != null) {
117 return result; 158 return result;
118 } 159 }
119 return addFrameSlot(identifier); 160 return addFrameSlot(identifier);
120 } 161 }
121 162
163 /**
164 * Finds an existing slot or creates new one. This is slow operation.
165 *
166 * @param identifier the key of the slot to search for
167 * @param kind the kind for the newly created slot
168 * @return the found or newly created slot
169 */
122 public FrameSlot findOrAddFrameSlot(Object identifier, FrameSlotKind kind) { 170 public FrameSlot findOrAddFrameSlot(Object identifier, FrameSlotKind kind) {
123 FrameSlot result = findFrameSlot(identifier); 171 FrameSlot result = findFrameSlot(identifier);
124 if (result != null) { 172 if (result != null) {
125 return result; 173 return result;
126 } 174 }
127 return addFrameSlot(identifier, kind); 175 return addFrameSlot(identifier, kind);
128 } 176 }
129 177
178 /**
179 * Finds an existing slot or creates new one. This is slow operation.
180 *
181 * @param identifier the key of the slot to search for
182 * @param info info for the newly created slot
183 * @param kind the kind for the newly created slot
184 * @return the found or newly created slot
185 */
130 public FrameSlot findOrAddFrameSlot(Object identifier, Object info, FrameSlotKind kind) { 186 public FrameSlot findOrAddFrameSlot(Object identifier, Object info, FrameSlotKind kind) {
131 FrameSlot result = findFrameSlot(identifier); 187 FrameSlot result = findFrameSlot(identifier);
132 if (result != null) { 188 if (result != null) {
133 return result; 189 return result;
134 } 190 }
135 return addFrameSlot(identifier, info, kind); 191 return addFrameSlot(identifier, info, kind);
136 } 192 }
137 193
194 /**
195 * Removes a slot. If the identifier is found, its slot is removed from this descriptor. This is
196 * slow operation.
197 *
198 * @param identifier identifies the slot to remove
199 */
138 public void removeFrameSlot(Object identifier) { 200 public void removeFrameSlot(Object identifier) {
139 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations."); 201 CompilerAsserts.neverPartOfCompilation("interpreter-only. includes hashmap operations.");
140 assert identifierToSlotMap.containsKey(identifier); 202 assert identifierToSlotMap.containsKey(identifier);
141 slots.remove(identifierToSlotMap.get(identifier)); 203 slots.remove(identifierToSlotMap.get(identifier));
142 identifierToSlotMap.remove(identifier); 204 identifierToSlotMap.remove(identifier);
198 260
199 private static Assumption createVersion() { 261 private static Assumption createVersion() {
200 return Truffle.getRuntime().createAssumption("frame version"); 262 return Truffle.getRuntime().createAssumption("frame version");
201 } 263 }
202 264
265 /**
266 * Default value for the created slots.
267 *
268 * @return value provided to {@link #FrameDescriptor(java.lang.Object)}
269 */
203 public Object getDefaultValue() { 270 public Object getDefaultValue() {
204 return defaultValue; 271 return defaultValue;
205 } 272 }
206 273
207 public Assumption getNotInFrameAssumption(Object identifier) { 274 public Assumption getNotInFrameAssumption(Object identifier) {