Ruby 4.1.0dev (2026-11-17 revision ebdf919795c0983696023691177045014435551c)
iseq.h (ebdf919795c0983696023691177045014435551c)
1#ifndef RUBY_ISEQ_H
2#define RUBY_ISEQ_H 1
3/**********************************************************************
4
5 iseq.h -
6
7 $Author$
8 created at: 04/01/01 23:36:57 JST
9
10 Copyright (C) 2004-2008 Koichi Sasada
11
12**********************************************************************/
13#include "internal/coverage.h"
14#include "internal/gc.h"
15#include "shape.h"
16#include "vm_core.h"
17
19#define ISEQ_MAJOR_VERSION ((unsigned int)ruby_api_version[0])
20#define ISEQ_MINOR_VERSION ((unsigned int)ruby_api_version[1])
21
22#define ISEQ_MBITS_SIZE sizeof(iseq_bits_t)
23#define ISEQ_MBITS_BITLENGTH (ISEQ_MBITS_SIZE * CHAR_BIT)
24#define ISEQ_MBITS_SET(buf, i) (buf[(i) / ISEQ_MBITS_BITLENGTH] |= ((iseq_bits_t)1 << ((i) % ISEQ_MBITS_BITLENGTH)))
25#define ISEQ_MBITS_SET_P(buf, i) ((buf[(i) / ISEQ_MBITS_BITLENGTH] >> ((i) % ISEQ_MBITS_BITLENGTH)) & 0x1)
26#define ISEQ_MBITS_BUFLEN(size) roomof(size, ISEQ_MBITS_BITLENGTH)
27
28#define ISEQ_LVAR_STATE_BITS 2
29#define ISEQ_LVAR_STATES_PER_BYTE (CHAR_BIT / ISEQ_LVAR_STATE_BITS)
30#define ISEQ_LVAR_STATES_BUFLEN(size) roomof(size, ISEQ_LVAR_STATES_PER_BYTE)
31#define ISEQ_LVAR_STATES_EMBED_P(size) (ISEQ_LVAR_STATES_BUFLEN(size) <= sizeof(uint8_t *))
32STATIC_ASSERT(lvar_state_fits_in_iseq_lvar_state_bits, lvar_reassigned < (1 << ISEQ_LVAR_STATE_BITS));
33
34static inline enum lvar_state
35iseq_lvar_state_get(const uint8_t *buf, unsigned int i)
36{
37 const unsigned int shift = (i % ISEQ_LVAR_STATES_PER_BYTE) * ISEQ_LVAR_STATE_BITS;
38 return (enum lvar_state)((buf[i / ISEQ_LVAR_STATES_PER_BYTE] >> shift) & ((1 << ISEQ_LVAR_STATE_BITS) - 1));
39}
40
41static inline void
42iseq_lvar_state_set(uint8_t *buf, unsigned int i, enum lvar_state state)
43{
44 uint8_t *const byte = &buf[i / ISEQ_LVAR_STATES_PER_BYTE];
45 const unsigned int shift = (i % ISEQ_LVAR_STATES_PER_BYTE) * ISEQ_LVAR_STATE_BITS;
46 *byte = (*byte & ~(((1 << ISEQ_LVAR_STATE_BITS) - 1) << shift)) | ((uint8_t)state << shift);
47}
48
49#ifndef rb_iseq_t
50typedef struct rb_iseq_struct rb_iseq_t;
51#define rb_iseq_t rb_iseq_t
52#endif
53
54extern const ID rb_iseq_shared_exc_local_tbl[];
55
56static inline bool
57iseq_has_lvar_states_p(const struct rb_iseq_constant_body *body)
58{
59 return body->local_table_size > 0 && body->local_table != rb_iseq_shared_exc_local_tbl;
60}
61
62static inline uint8_t *
63iseq_lvar_states(const struct rb_iseq_constant_body *body)
64{
65 if (ISEQ_LVAR_STATES_EMBED_P(body->local_table_size)) {
66 return (uint8_t *)body->lvar_states.single;
67 }
68 else {
69 return body->lvar_states.list;
70 }
71}
72
73/* Ensure body->variable is allocated, returning the struct. */
74struct rb_iseq_variable *rb_iseq_variable_ensure(rb_iseq_t *iseq);
75
76static inline struct rb_iseq_variable *
77ISEQ_BODY_VARIABLE(const rb_iseq_t *iseq)
78{
79 return ISEQ_BODY(iseq)->variable;
80}
81
82/* NULL-safe read accessors for body->variable fields. */
83static inline VALUE
84ISEQ_BODY_VARIABLE_SCRIPT_LINES(const rb_iseq_t *iseq)
85{
86 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
87 return v ? v->script_lines : Qnil;
88}
89
90static inline VALUE
91ISEQ_BODY_VARIABLE_COVERAGE(const rb_iseq_t *iseq)
92{
93 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
94 return v ? v->coverage : Qfalse;
95}
96
97static inline VALUE
98ISEQ_BODY_VARIABLE_PC2BRANCHINDEX(const rb_iseq_t *iseq)
99{
100 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
101 return v ? v->pc2branchindex : Qfalse;
102}
103
104static inline rb_snum_t
105ISEQ_BODY_VARIABLE_FLIP_CNT(const rb_iseq_t *iseq)
106{
107 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
108 return v ? v->flip_count : 0;
109}
110
111static inline VALUE *
112ISEQ_BODY_VARIABLE_ORIGINAL_ISEQ(const rb_iseq_t *iseq)
113{
114 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
115 return v ? v->original_iseq : NULL;
116}
117
118/* Write accessors (lazily allocate variable as needed). */
119void rb_iseq_coverage_set(rb_iseq_t *iseq, VALUE cov);
120void rb_iseq_pc2branchindex_set(rb_iseq_t *iseq, VALUE h);
121rb_snum_t rb_iseq_flip_cnt_increment(const rb_iseq_t *iseq);
122
123/* Short macros for reading variable fields. */
124#define ISEQ_VARIABLE(iseq) ISEQ_BODY_VARIABLE(iseq)
125#define ISEQ_SCRIPT_LINES(iseq) ISEQ_BODY_VARIABLE_SCRIPT_LINES(iseq)
126#define ISEQ_COVERAGE(iseq) ISEQ_BODY_VARIABLE_COVERAGE(iseq)
127#define ISEQ_COVERAGE_SET(iseq, cov) rb_iseq_coverage_set(iseq, cov)
128#define ISEQ_LINE_COVERAGE(iseq) RARRAY_AREF(ISEQ_COVERAGE(iseq), COVERAGE_INDEX_LINES)
129#define ISEQ_BRANCH_COVERAGE(iseq) RARRAY_AREF(ISEQ_COVERAGE(iseq), COVERAGE_INDEX_BRANCHES)
130
131#define ISEQ_PC2BRANCHINDEX(iseq) ISEQ_BODY_VARIABLE_PC2BRANCHINDEX(iseq)
132#define ISEQ_PC2BRANCHINDEX_SET(iseq,h) rb_iseq_pc2branchindex_set(iseq, h)
133
134#define ISEQ_FLIP_CNT(iseq) ISEQ_BODY_VARIABLE_FLIP_CNT(iseq)
135#define ISEQ_FLIP_CNT_INCREMENT(iseq) rb_iseq_flip_cnt_increment(iseq)
136#define ISEQ_ORIGINAL_ISEQ(iseq) ISEQ_BODY_VARIABLE_ORIGINAL_ISEQ(iseq)
137
138#define ISEQ_FROZEN_STRING_LITERAL_ENABLED 1
139#define ISEQ_FROZEN_STRING_LITERAL_DISABLED 0
140#define ISEQ_FROZEN_STRING_LITERAL_UNSET -1
141
142static inline void
143ISEQ_ORIGINAL_ISEQ_CLEAR(const rb_iseq_t *iseq)
144{
145 struct rb_iseq_variable *v = ISEQ_BODY_VARIABLE(iseq);
146 if (v) {
147 VALUE *ptr = v->original_iseq;
148 if (ptr) {
149 v->original_iseq = NULL;
150 SIZED_FREE_N(ptr, ISEQ_BODY(iseq)->iseq_size);
151 }
152 }
153}
154
155#define ISEQ_TRACE_EVENTS (RUBY_EVENT_LINE | \
156 RUBY_EVENT_CLASS | \
157 RUBY_EVENT_END | \
158 RUBY_EVENT_CALL | \
159 RUBY_EVENT_RETURN| \
160 RUBY_EVENT_C_CALL| \
161 RUBY_EVENT_C_RETURN | \
162 RUBY_EVENT_B_CALL | \
163 RUBY_EVENT_B_RETURN | \
164 RUBY_EVENT_RESCUE | \
165 RUBY_EVENT_COVERAGE_LINE| \
166 RUBY_EVENT_COVERAGE_BRANCH)
167
168#define ISEQ_NOT_LOADED_YET IMEMO_FL_USER1
169#define ISEQ_USE_COMPILE_DATA IMEMO_FL_USER2
170/* set once iseq_encoded is in its executable form, with or without threaded code */
171#define ISEQ_TRANSLATED IMEMO_FL_USER3
172/* set on every iseq of a subtree copied for Proc#refined */
173#define ISEQ_REFINED_COPY IMEMO_FL_USER4
174
175#define ISEQ_EXECUTABLE_P(iseq) (FL_TEST_RAW(((VALUE)iseq), ISEQ_NOT_LOADED_YET | ISEQ_USE_COMPILE_DATA) == 0)
176
178 /* GC is needed */
179 const VALUE err_info;
180 const VALUE catch_table_ary; /* Array */
181
182 /* Mirror fields from ISEQ_BODY so they are accessible during iseq setup */
183 unsigned int iseq_size;
184 VALUE *iseq_encoded; /* half-encoded iseq (insn addr and operands) */
185 bool is_single_mark_bit; /* identifies whether mark bits are single or a list */
186
187 union {
188 iseq_bits_t * list; /* Find references for GC */
189 iseq_bits_t single;
190 } mark_bits;
191
192 /* GC is not needed */
193 struct iseq_label_data *start_label;
194 struct iseq_label_data *end_label;
195 struct iseq_label_data *redo_label;
196 const rb_iseq_t *current_block;
197 struct iseq_compile_data_ensure_node_stack *ensure_node_stack;
198 struct {
199 struct iseq_compile_data_storage *storage_head;
200 struct iseq_compile_data_storage *storage_current;
201 } node;
202 struct {
203 struct iseq_compile_data_storage *storage_head;
204 struct iseq_compile_data_storage *storage_current;
205 } insn;
206 bool in_rescue;
207 int loopval_popped; /* used by NODE_BREAK */
208 int last_line;
209 int label_no;
210 int node_level;
211 int isolated_depth;
212 unsigned int ci_index;
213 unsigned int ic_index;
214 const rb_compile_option_t *option;
215 struct rb_id_table *ivar_cache_table;
216 const struct rb_builtin_function *builtin_function_table;
217 const NODE *root_node;
218 bool catch_except_p; // If a frame of this ISeq may catch exception, set true.
219#if OPT_SUPPORT_JOKE
220 st_table *labels_table;
221#endif
222};
223
224static inline struct iseq_compile_data *
225ISEQ_COMPILE_DATA(const rb_iseq_t *iseq)
226{
227 if (iseq->flags & ISEQ_USE_COMPILE_DATA) {
228 return iseq->aux.compile_data;
229 }
230 else {
231 return NULL;
232 }
233}
234
235static inline void
236ISEQ_COMPILE_DATA_ALLOC(rb_iseq_t *iseq)
237{
238 iseq->aux.compile_data = ZALLOC(struct iseq_compile_data);
239 iseq->flags |= ISEQ_USE_COMPILE_DATA;
240}
241
242static inline void
243ISEQ_COMPILE_DATA_CLEAR(rb_iseq_t *iseq)
244{
245 iseq->flags &= ~ISEQ_USE_COMPILE_DATA;
246 iseq->aux.compile_data = NULL;
247}
248
249static inline rb_iseq_t *
250iseq_imemo_alloc(void)
251{
252 rb_iseq_t *iseq = SHAREABLE_IMEMO_NEW(rb_iseq_t, imemo_iseq, 0);
253
254 // Clear out the whole iseq except for the flags.
255 memset((char *)iseq + sizeof(VALUE), 0, sizeof(rb_iseq_t) - sizeof(VALUE));
256
257 return iseq;
258}
259
260VALUE rb_iseq_ibf_dump(const rb_iseq_t *iseq, VALUE opt);
261void rb_ibf_load_iseq_complete(rb_iseq_t *iseq);
262const rb_iseq_t *rb_iseq_ibf_load(VALUE str);
263const rb_iseq_t *rb_iseq_ibf_load_bytes(const char *cstr, size_t);
264VALUE rb_iseq_ibf_load_extra_data(VALUE str);
265const rb_iseq_t *rb_iseq_dup_with_independent_caches(const rb_iseq_t *iseq);
266void rb_iseq_init_trace(rb_iseq_t *iseq);
267int rb_iseq_add_local_tracepoint_recursively(const rb_iseq_t *iseq, rb_event_flag_t turnon_events, VALUE tpval, unsigned int target_line, bool target_bmethod);
268int rb_iseq_remove_local_tracepoint_recursively(const rb_iseq_t *iseq, VALUE tpval, rb_ractor_t *r);
269const rb_iseq_t *rb_iseq_load_iseq(VALUE fname);
270const rb_iseq_t *rb_iseq_compile_iseq(VALUE str, VALUE fname);
271int rb_iseq_opt_frozen_string_literal(void);
272rb_hook_list_t *rb_iseq_local_hooks(const rb_iseq_t *iseq, rb_ractor_t *r, bool create);
273
274
275#if VM_INSN_INFO_TABLE_IMPL == 2
276unsigned int *rb_iseq_insns_info_decode_positions(const struct rb_iseq_constant_body *body);
277#endif
278
279int rb_vm_insn_addr2opcode(const void *addr);
280
281RUBY_SYMBOL_EXPORT_BEGIN
282
283/* compile.c */
284VALUE rb_iseq_compile_node(rb_iseq_t *iseq, const NODE *node);
285VALUE rb_iseq_compile_callback(rb_iseq_t *iseq, const struct rb_iseq_new_with_callback_callback_func * ifunc);
286VALUE *rb_iseq_original_iseq(const rb_iseq_t *iseq);
287void rb_iseq_build_from_ary(rb_iseq_t *iseq, VALUE misc,
288 VALUE locals, VALUE args,
289 VALUE exception, VALUE body);
290void rb_iseq_mark_and_move_insn_storage(struct iseq_compile_data_storage *arena);
291
292VALUE rb_iseq_load(VALUE data, VALUE parent, VALUE opt);
293VALUE rb_iseq_parameters(const rb_iseq_t *iseq, int is_proc);
294unsigned int rb_iseq_line_no(const rb_iseq_t *iseq, size_t pos);
295#ifdef USE_ISEQ_NODE_ID
296int rb_iseq_node_id(const rb_iseq_t *iseq, size_t pos);
297#endif
298void rb_iseq_trace_set(const rb_iseq_t *iseq, rb_event_flag_t turnon_events);
299void rb_iseq_trace_set_all(rb_event_flag_t turnon_events);
300void rb_iseq_insns_info_encode_positions(const rb_iseq_t *iseq);
301
302struct rb_iseq_constant_body *rb_iseq_constant_body_alloc(void);
303VALUE rb_iseqw_new(const rb_iseq_t *iseq);
304const rb_iseq_t *rb_iseqw_to_iseq(VALUE iseqw);
305
306VALUE rb_iseq_absolute_path(const rb_iseq_t *iseq); /* obsolete */
307int rb_iseq_from_eval_p(const rb_iseq_t *iseq);
308VALUE rb_iseq_type(const rb_iseq_t *iseq);
309VALUE rb_iseq_label(const rb_iseq_t *iseq);
310VALUE rb_iseq_base_label(const rb_iseq_t *iseq);
311VALUE rb_iseq_first_lineno(const rb_iseq_t *iseq);
312VALUE rb_iseq_method_name(const rb_iseq_t *iseq);
313void rb_iseq_code_location(const rb_iseq_t *iseq, int *first_lineno, int *first_column, int *last_lineno, int *last_column);
314
315void rb_iseq_remove_coverage_all(void);
316
317/* proc.c */
318const rb_iseq_t *rb_method_iseq(VALUE body);
319const rb_iseq_t *rb_proc_get_iseq(VALUE proc, int *is_proc);
320
322 unsigned int inline_const_cache: 1;
323 unsigned int peephole_optimization: 1;
324 unsigned int tailcall_optimization: 1;
325 unsigned int specialized_instruction: 1;
326 unsigned int operands_unification: 1;
327 unsigned int instructions_unification: 1;
328 signed int frozen_string_literal: 2; /* -1: not specified, 0: false, 1: true */
329 unsigned int debug_frozen_string_literal: 1;
330 unsigned int coverage_enabled: 1;
331 int debug_level;
332};
333
335 int line_no;
336 rb_event_flag_t events;
337};
338
339/*
340 * iseq type:
341 * CATCH_TYPE_RESCUE, CATCH_TYPE_ENSURE:
342 * use iseq as continuation.
343 *
344 * CATCH_TYPE_BREAK (iter):
345 * use iseq as key.
346 *
347 * CATCH_TYPE_BREAK (while), CATCH_TYPE_RETRY,
348 * CATCH_TYPE_REDO, CATCH_TYPE_NEXT:
349 * NULL.
350 */
351enum rb_catch_type {
352 CATCH_TYPE_RESCUE = INT2FIX(1),
353 CATCH_TYPE_ENSURE = INT2FIX(2),
354 CATCH_TYPE_RETRY = INT2FIX(3),
355 CATCH_TYPE_BREAK = INT2FIX(4),
356 CATCH_TYPE_REDO = INT2FIX(5),
357 CATCH_TYPE_NEXT = INT2FIX(6)
358};
359
361 enum rb_catch_type type;
362 rb_iseq_t *iseq;
363
364 unsigned int start;
365 unsigned int end;
366 unsigned int cont;
367 unsigned int sp;
368};
369
370RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN()
372 unsigned int size;
373 struct iseq_catch_table_entry entries[FLEX_ARY_LEN];
374} RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END();
375
376static inline int
377iseq_catch_table_bytes(int n)
378{
379 enum {
380 catch_table_entry_size = sizeof(struct iseq_catch_table_entry),
381 catch_table_entries_max = (INT_MAX - offsetof(struct iseq_catch_table, entries)) / catch_table_entry_size
382 };
383 if (n > catch_table_entries_max) rb_fatal("too large iseq_catch_table - %d", n);
384 return (int)(offsetof(struct iseq_catch_table, entries) +
385 n * catch_table_entry_size);
386}
387
388#define INITIAL_ISEQ_COMPILE_DATA_STORAGE_BUFF_SIZE (512)
389
391 struct iseq_compile_data_storage *next;
392 unsigned int pos;
393 unsigned int size;
394 char buff[FLEX_ARY_LEN];
395};
396
397/* defined? */
398
399enum defined_type {
400 DEFINED_NOT_DEFINED,
401 DEFINED_NIL = 1,
402 DEFINED_IVAR,
403 DEFINED_LVAR,
404 DEFINED_GVAR,
405 DEFINED_CVAR,
406 DEFINED_CONST,
407 DEFINED_METHOD,
408 DEFINED_YIELD,
409 DEFINED_ZSUPER,
410 DEFINED_SELF,
411 DEFINED_TRUE,
412 DEFINED_FALSE,
413 DEFINED_ASGN,
414 DEFINED_EXPR,
415 DEFINED_REF,
416 DEFINED_FUNC,
417 DEFINED_CONST_FROM
418};
419
420VALUE rb_iseq_defined_string(enum defined_type type);
421
422/* vm.c */
423VALUE rb_iseq_local_variables(const rb_iseq_t *iseq);
424
425attr_index_t rb_estimate_iv_count(VALUE klass, const rb_iseq_t * initialize_iseq);
426
427void rb_free_encoded_insn_data(void);
428
429RUBY_SYMBOL_EXPORT_END
430
431#endif /* RUBY_ISEQ_H */
#define RUBY_EXTERN
Declaration of externally visible global variables.
Definition dllexport.h:45
uint32_t rb_event_flag_t
Represents event(s).
Definition event.h:108
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
#define ZALLOC
Old name of RB_ZALLOC.
Definition memory.h:405
#define Qnil
Old name of RUBY_Qnil.
#define Qfalse
Old name of RUBY_Qfalse.
const int ruby_api_version[3]
API versions, in { major, minor, teeny } order.
Definition version.c:55
VALUE type(ANYARGS)
ANYARGS-ed function type.
Definition iseq.h:360
Definition iseq.h:334
Definition st.h:79
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40