blib/lib/SPVM/Document/NativeAPI/Runtime.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 =head1 Name
2  
3 SPVM::Document::NativeAPI::Runtime - Runtime Native APIs
4  
5 =head1 Description
6  
7 The runtime native APIs of L<SPVM> are the APIs for SPVM runtimes.
8  
9 =head1 Usage
10  
11 SPVM_API_RUNTIME* api_runtime = env->api->runtime;
12
13 int32_t basic_types_length = api_runtime->get_basic_types_length(env->runtime);
14  
15 =head1 Runtime Native APIs
16  
17 =head2 get_object_data_offset
18  
19 C<int32_t (*get_object_data_offset)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
20  
21 Returns the offset of data area in L<SPVM_OBJECT|SPVM::Document::NativeAPI/"SPVM_OBJECT"> struct.
22  
23 Elements in an array or fields or a pointer in a pointer class is stored into the data area.
24  
25 =head2 get_object_ref_count_offset
26  
27 C<int32_t (*get_object_ref_count_offset)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
28  
29 Returns the offset of the C<ref_count> field in L<SPVM_OBJECT|SPVM::Document::NativeAPI/"SPVM_OBJECT"> struct.
30  
31 =head2 get_object_length_offset
32  
33 C<int32_t (*get_object_length_offset)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
34  
35 Returns the offset of the C<length> field in L<SPVM_OBJECT|SPVM::Document::NativeAPI/"SPVM_OBJECT"> struct.
36  
37 =head2 get_basic_type_by_id
38  
39 C<SPVM_NATIVE_BASIC_TYPE* (*get_basic_type_by_id)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, int32_t basic_type_id);>
40  
41 Searches a L<basic type|SPVM::Document::NativeAPI::BasicType> given the basic type ID I<basic_type_id>.
42  
43 If it is found, returns it. Otherwise, returns C<NULL>.
44  
45 =head2 get_basic_type_by_name
46  
47 C<SPVM_NATIVE_BASIC_TYPE* (*get_basic_type_by_name)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, const char* basic_type_name);>
48  
49 Searches a L<basic type|SPVM::Document::NativeAPI::BasicType> given the basic type name I<basic_type_name>.
50  
51 If it is found, returns it. Otherwise, returns C<NULL>.
52  
53 =head2 get_basic_types_length
54  
55 C<int32_t (*get_basic_types_length)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
56  
57 Returns the length of the basic types owned by the SPVM runtime I<runtime>.
58  
59 =head2 build_precompile_class_source
60  
61 C<void (*build_precompile_class_source)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, L<SPVM_NATIVE_STRING_BUFFER* string_buffer|SPVM::Document::NativeAPI::StringBuffer>, L<SPVM_NATIVE_BASIC_TYPE* basic_type|SPVM::Document::NativeAPI::BasicType>);>
62  
63 Creates a C source code for methods with the C<precompile> attribute defined in the class given by the its basic type I<basic_type>, and saves it to the string buffer I<string_buffer>.
64  
65 =head2 build_precompile_method_source
66  
67 C<void (*build_precompile_method_source)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, L<SPVM_NATIVE_STRING_BUFFER* string_buffer|SPVM::Document::NativeAPI::StringBuffer>, L<SPVM_NATIVE_METHOD* method|SPVM::Document::NativeAPI::Method>);>
68  
69 Creates a C source code for the method I<method>, and saves it to the string buffer I<string_buffer>.
70  
71 =head2 get_compiler
72  
73 C<SPVM_NATIVE_COMPILER* (*get_compiler)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
74  
75 Returns the value of the C<compiler> field. The compiler that build the runtime I<runtime> is stored to this field.
76  
77 =head2 set_compiler
78  
79 C<void (*set_compiler)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, L<SPVM_NATIVE_COMPILER* compiler|SPVM::Document::NativeAPI::Compiler>);>
80  
81 Sets I<compiler> to the C<compiler> field.
82  
83 =head2 get_spvm_stdin
84  
85 C<FILE* (*get_spvm_stdin)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
86  
87 Returns L<SPVM's standard input|SPVM::Document::Language::System/"Standard Streams">.
88  
89 =head2 get_spvm_stdout
90  
91 C<FILE* (*get_spvm_stdout)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
92  
93 Returns L<SPVM's standard output|SPVM::Document::Language::System/"Standard Streams">.
94  
95 =head2 get_spvm_stderr
96  
97 C<FILE* (*get_spvm_stderr)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
98  
99 Returns L<SPVM's standard error|SPVM::Document::Language::System/"Standard Streams">.
100  
101 =head2 get_env
102  
103 C<SPVM_ENV* (*get_env)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
104  
105 Returns the runtime environment.
106  
107 =head2 get_object_capacity_offset
108  
109 C<int32_t (*get_object_capacity_offset)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
110  
111 Returns the offset of C<capacity> member variable in L<SPVM_OBJECT|SPVM::Document::NativeAPI/"SPVM_OBJECT"> struct.
112  
113 =head2 method_begin_cb
114  
115 C<void* method_begin_cb;>
116  
117 The callback function called at the beginning of a method.
118  
119 The callback function must be a function pointer with the following signature:
120  
121 C<void cb(L<SPVM_ENV* env|SPVM::Document::NativeAPI>, L<SPVM_VALUE* stack|SPVM::Document::NativeAPI::Value>);>
122  
123 =over 2
124  
125 =item * I<env> : The runtime environment.
126  
127 =item * I<stack> : The runtime stack. This can be used to access arguments.
128  
129 =back
130  
131 =head2 method_end_cb
132  
133 C<void* method_end_cb;>
134  
135 The callback function called at the end of a method.
136  
137 The callback function must be a function pointer with the following signature:
138  
139 C<void cb(L<SPVM_ENV* env|SPVM::Document::NativeAPI>, L<SPVM_VALUE* stack|SPVM::Document::NativeAPI::Value>);>
140  
141 The arguments are the same as L</"method_begin_cb">. This can be used to access the return value.
142  
143 =head2 object_data_offset
144  
145 C<void* object_data_offset;>
146  
147 Returns the offset of C<data> member variable in C<SPVM_OBJECT> object. This must not be used because it is only for internal.
148  
149 =head2 object_length_offset
150  
151 C<void* object_length_offset;>
152  
153 Returns the offset of C<length> member variable in C<SPVM_OBJECT> object. This must not be used because it is only for internal.
154  
155 =head2 object_capacity_offset
156  
157 C<void* object_capacity_offset;>
158  
159 Returns the offset of C<capacity> member variable in C<SPVM_OBJECT> object. This must not be used because it is only for internal.
160  
161 =head2 stack_index_call_depth
162  
163 C<void* stack_index_call_depth;>
164  
165 The index of the C<call_depth> stack variable on the runtime stack. This value is cast to C<void*>.
166  
167 Examples:
168  
169 int32_t call_depth_index = (int32_t)(intptr_t)env->api->runtime->stack_index_call_depth;
170 int32_t call_depth = stack[call_depth_index].ival;
171  
172 =head2 stack_index_caller_info_stack
173  
174 C<void* stack_index_caller_info_stack;>
175  
176 The index of the C<caller_info_stack> stack variable on the runtime stack. This value is cast to C<void*>.
177  
178 Examples:
179  
180 int32_t caller_info_stack_index = (int32_t)(intptr_t)env->api->runtime->stack_index_caller_info_stack;
181 void** caller_info_stack = (void**)stack[caller_info_stack_index].oval;
182  
183 =head2 stack_index_caller_info_stack_record_size
184  
185 C<void* stack_index_caller_info_stack_record_size;>
186  
187 The index of the C<caller_info_stack_record_size> stack variable on the runtime stack. This value is cast to C<void*>.
188  
189 Examples:
190  
191 int32_t record_size_index = (int32_t)(intptr_t)env->api->runtime->stack_index_caller_info_stack_record_size;
192 int32_t record_size = stack[record_size_index].ival;
193  
194 =head2 enable_record_object
195  
196 C<void (*enable_record_object)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
197  
198 Enables object recording for memory leak tracking.
199  
200 =head2 disable_record_object
201  
202 C<void (*disable_record_object)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
203  
204 Disables object recording for memory leak tracking.
205  
206 =head2 get_mutex
207  
208 C<SPVM_NATIVE_MUTEX* (*get_mutex)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>);>
209  
210 Returns the runtime mutex.
211  
212 =head2 get_field_by_abs_name
213  
214 C<SPVM_RUNTIME_FIELD* (*get_field_by_abs_name)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, const char* field_abs_name);>
215  
216 Searches a field given the field absolute name I<field_abs_name> such as C<MyClass#foo>
217  
218 If it is found, returns it. Otherwise, returns C<NULL>.
219  
220 =head2 get_class_var_by_abs_name
221  
222 C<SPVM_RUNTIME_CLASS_VAR* (*get_class_var_by_abs_name)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, const char* class_var_abs_name);>
223  
224 Searches a class variable given the class variable absolute name I<class_var_abs_name> such as C<MyClass#FOO>.
225  
226 If it is found, returns it. Otherwise, returns C<NULL>.
227  
228 =head2 get_method_by_abs_name
229  
230 C<SPVM_RUNTIME_METHOD* (*get_method_by_abs_name)(L<SPVM_NATIVE_RUNTIME* runtime|SPVM::Document::NativeAPI::Runtime>, const char* method_abs_name);>
231  
232 Searches a method given the method absolute name I<method_abs_name> such as C<MyClass#foo>.
233  
234 If it is found, returns it. Otherwise, returns C<NULL>.
235  
236 =head1 Native Runtime API IDs
237  
238 0 get_object_data_offset
239 1 get_object_ref_count_offset
240 2 get_object_length_offset
241 3 get_basic_type_by_id
242 4 get_basic_type_by_name
243 5 get_basic_types_length
244 6 build_precompile_class_source
245 7 build_precompile_method_source
246 8 get_compiler
247 9 set_compiler
248 10 get_spvm_stdin
249 11 get_spvm_stdout
250 12 get_spvm_stderr
251 13 get_env
252 14 get_object_capacity_offset
253 15 method_begin_cb
254 16 method_end_cb
255 17 object_data_offset
256 18 object_length_offset
257 19 object_capacity_offset
258 20 stack_index_call_depth
259 21 stack_index_caller_info_stack
260 22 stack_index_caller_info_stack_record_size
261 23 enable_record_object
262 24 disable_record_object
263 25 get_mutex
264 26 get_field_by_abs_name
265 27 get_class_var_by_abs_name
266 28 get_method_by_abs_name
267
268 =head1 See Also
269  
270 =over 2
271  
272 =item * L<SPVM::Document::NativeAPI>
273  
274 =item * L<SPVM::Document::NativeAPI::BasicType>
275  
276 =item * L<SPVM::Document::NativeAPI::Method>
277  
278 =item * L<SPVM::Document::NativeAPI::StringBuffer>
279  
280 =item * L<SPVM::Document::NativeAPI::Compiler>
281  
282 =item * L<SPVM::Document::NativeClass>
283  
284 =item * L<SPVM::Document>
285  
286 =back
287  
288 =head1 Copyright & License
289  
290 Copyright (c) 2023 Yuki Kimoto
291  
292 MIT License