« blib/lib/SPVM/Document/NativeAPI/Mutex.pm
↑ Summary
blib/lib/SPVM/Document/NativeAPI/StringBuffer.pm »
| 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 |