| 1 | =head1 Name | ||
| 2 | |||
| 3 | SPVM::Document::NativeClass - Native Classes | ||
| 4 | |||
| 5 | =head1 Description | ||
| 6 | |||
| 7 | A native class is the class implemented by a native language such as the C language and C++. | ||
| 8 | |||
| 9 | =head1 Native Method Definition | ||
| 10 | |||
| 11 | A native method is defined by L<native method attribute|SPVM::Document::Language::Class/"Method Attributes"> in an SPVM class file. It ends with a semicolon. A native method does not have its block. | ||
| 12 | |||
| 13 | # SPVM/MyClass.spvm | ||
| 14 | class MyClass { | ||
| 15 | native static method sum : int ($num1 : int, $num2 : int); | ||
| 16 | } | ||
| 17 | |||
| 18 | =head1 Native Config File | ||
| 19 | |||
| 20 | A native config file is needed for a native class. The name of the config file is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.build>. | ||
| 21 | |||
| 22 | # The name of a native config file | ||
| 23 | SPVM/MyClass.build | ||
| 24 | |||
| 25 | A native config file is writen by Perl. It must end with a L<Builder::Config|SPVM::Builder::Config> object. | ||
| 26 | |||
| 27 | A config file is executed by Perl's L<do|https://perldoc.perl.org/functions/do> function. The returned L<Builder::Config|SPVM::Builder::Config> object is used as the config for a native class. | ||
| 28 | |||
| 29 | Exceptions: | ||
| 30 | |||
| 31 | If the native config file does not exist, an exception is thrown. | ||
| 32 | |||
| 33 | A config file must end with a L<Builder::Config|SPVM::Builder::Config> object. Otherwise, an exception is thrown. | ||
| 34 | |||
| 35 | Examples: | ||
| 36 | |||
| 37 | C99: | ||
| 38 | |||
| 39 | my $config = SPVM::Builder::Config->new_c99; | ||
| 40 | |||
| 41 | $config; | ||
| 42 | |||
| 43 | C++: | ||
| 44 | |||
| 45 | my $config = SPVM::Builder::Config->new_cpp; | ||
| 46 | |||
| 47 | $config; | ||
| 48 | |||
| 49 | =head1 Native Class | ||
| 50 | |||
| 51 | A native class is the class implemented by a native language such as the C language and C++. | ||
| 52 | |||
| 53 | The name of the native class file is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.> and L<extension of the native class|/"Native Class File Extension">. | ||
| 54 | |||
| 55 | SPVM/MyClass.c | ||
| 56 | |||
| 57 | =head2 Native Class File Extension | ||
| 58 | |||
| 59 | The file extension of a native class is defined by L<Builder::Config#ext|SPVM::Builder::Config/"ext"> field in a config file. | ||
| 60 | |||
| 61 | Examples: | ||
| 62 | |||
| 63 | $config->ext('c'); | ||
| 64 | |||
| 65 | $config->ext('cpp'); | ||
| 66 | |||
| 67 | $config->ext('cc'); | ||
| 68 | |||
| 69 | $config->ext('cu'); | ||
| 70 | |||
| 71 | Exceptions: | ||
| 72 | |||
| 73 | If L<ext|SPVM::Builder::Config/"ext"> is defined, but its corresponding config file does not exist, an exception is thrown. | ||
| 74 | |||
| 75 | =head2 Native Function | ||
| 76 | |||
| 77 | A native function is a function defined in a native class. | ||
| 78 | |||
| 79 | Examples: | ||
| 80 | |||
| 81 | // SPVM/MyClass.c | ||
| 82 | |||
| 83 | #include "spvm_native.h" | ||
| 84 | |||
| 85 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 86 | |||
| 87 | int32_t num1 = stack[0].ival; | ||
| 88 | int32_t num2 = stakc[1].ival; | ||
| 89 | |||
| 90 | int32_t total = num1 + num2; | ||
| 91 | |||
| 92 | stack[0].ival = total; | ||
| 93 | |||
| 94 | return 0; | ||
| 95 | } | ||
| 96 | |||
| 97 | =head3 Native Function Name | ||
| 98 | |||
| 99 | A native function must have the name following the rules below. | ||
| 100 | |||
| 101 | =over 2 | ||
| 102 | |||
| 103 | =item * 1. Starts with C<SPVM__>. | ||
| 104 | |||
| 105 | =item * 2. Followed by the SPVM class name, but C<::> is replaced with C<__>. | ||
| 106 | |||
| 107 | =item * 3. Followed by C<__>. | ||
| 108 | |||
| 109 | =item * 3. Followed by the name of the method. | ||
| 110 | |||
| 111 | =back | ||
| 112 | |||
| 113 | Exceptions: | ||
| 114 | |||
| 115 | If the name of a native function is invalid, an exception is thrown. | ||
| 116 | |||
| 117 | Examples: | ||
| 118 | |||
| 119 | For example, if the class is C<MyClass::Math> and the method name is C<sum_value>, the name of the native function is C<SPVM__MyClass__Math__sum_value>. | ||
| 120 | |||
| 121 | # SPVM class | ||
| 122 | class MyClass::Math { | ||
| 123 | native method sum_value : void (); | ||
| 124 | } | ||
| 125 | |||
| 126 | // Native class | ||
| 127 | SPVM__MyClass__Math__sum_value(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 128 | |||
| 129 | } | ||
| 130 | |||
| 131 | =head2 Native API Header | ||
| 132 | |||
| 133 | #include "spvm_native.h" | ||
| 134 | |||
| 135 | C<spvm_native.h> is the header file for L<SPVM Native APIs|SPVM::Document::NativeAPI>. | ||
| 136 | |||
| 137 | The following standard C headers are guaranteed to be available and can be used by default in your native code: | ||
| 138 | |||
| 139 | #include <stdint.h> | ||
| 140 | #include <stdio.h> | ||
| 141 | #include <string.h> | ||
| 142 | #include <stdlib.h> | ||
| 143 | #include <inttypes.h> | ||
| 144 | #include <assert.h> | ||
| 145 | |||
| 146 | These headers are highly portable and compatible with major compilers including GCC, Clang, and MSVC. | ||
| 147 | |||
| 148 | =head2 Native Function Arguments | ||
| 149 | |||
| 150 | A native function must have two arguments. | ||
| 151 | |||
| 152 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 153 | |||
| 154 | } | ||
| 155 | |||
| 156 | The first argument C<env> is the current L<runtime environment|/"Runtime Environment">. This is the pointer to a value of C<SPVM_ENV> type. | ||
| 157 | |||
| 158 | The second argument C<stack> is the current L<runtime stack|/"Runtime Stack">. This is is the pointer to the values of L<SPVM_VALUE|/"SPVM_VALUE Type"> type. | ||
| 159 | |||
| 160 | The arguments given to this native function have been stored in the runtime stack. | ||
| 161 | |||
| 162 | See L</"Getting Argument"> to get the values of the arguments. | ||
| 163 | |||
| 164 | =head2 Native Function Return Value | ||
| 165 | |||
| 166 | A native function must return a value of the C<int32_t> type. | ||
| 167 | |||
| 168 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 169 | |||
| 170 | # ... | ||
| 171 | |||
| 172 | return 0; | ||
| 173 | } | ||
| 174 | |||
| 175 | If an exception is thrown in this native method, the native function must return a non-zero value. Otherwise, must return 0. | ||
| 176 | |||
| 177 | See L</"Exception"> for exception handling in native classes. | ||
| 178 | |||
| 179 | =head2 SPVM_VALUE Type | ||
| 180 | |||
| 181 | C<SPVM_VALUE> type is an union type in the C language. | ||
| 182 | |||
| 183 | typedef union spvm_value SPVM_VALUE; | ||
| 184 | |||
| 185 | union spvm_value { | ||
| 186 | int8_t bval; | ||
| 187 | int16_t sval; | ||
| 188 | int32_t ival; | ||
| 189 | int64_t lval; | ||
| 190 | float fval; | ||
| 191 | double dval; | ||
| 192 | SPVM_OBJ* oval; | ||
| 193 | SPVM_REF* ref; | ||
| 194 | void* address; | ||
| 195 | int8_t* bref; | ||
| 196 | int16_t* sref; | ||
| 197 | int32_t* iref; | ||
| 198 | int64_t* lref; | ||
| 199 | float* fref; | ||
| 200 | double* dref; | ||
| 201 | }; | ||
| 202 | |||
| 203 | =head2 Getting Argument | ||
| 204 | |||
| 205 | Arguments given to a native function have been stored in L<runtime stack|/"Runtime Stack"> I<stack>. | ||
| 206 | |||
| 207 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 208 | |||
| 209 | } | ||
| 210 | |||
| 211 | Consider the following method definition. | ||
| 212 | |||
| 213 | method foo ($args0 : int, $args1 : Point, $arg2 : Complex_2d); | ||
| 214 | |||
| 215 | Do the following using the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of $args0 which type is int type. | ||
| 216 | |||
| 217 | int32_t args0 = stack[0].ival; | ||
| 218 | |||
| 219 | Do the following using the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of $args1 which type is L<Point|SPVM::Point> type. | ||
| 220 | |||
| 221 | int64_t args1 = stack[1].oval; | ||
| 222 | |||
| 223 | Do the following to get the values of $args2 which type is L<Complex_2d|SPVM::Complex_2d> multi-numeric type. | ||
| 224 | |||
| 225 | double args2_re = stack[2].dval; | ||
| 226 | double args2_im = stack[3].dval; | ||
| 227 | |||
| 228 | Note that the values of the multi-numeric type have been stored in the multiple values in the runtime stack. The length of the value in the runtime stack is the same as the length of the fields of the multi-numeric type. | ||
| 229 | |||
| 230 | =head3 Getting byte Type Argument | ||
| 231 | |||
| 232 | Use the C<bval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<byte> type from an argument. | ||
| 233 | |||
| 234 | int8_t args0 = stack[0].bval; | ||
| 235 | |||
| 236 | =head3 Getting short Type Argument | ||
| 237 | |||
| 238 | Use the C<sval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<short> type from an argument. | ||
| 239 | |||
| 240 | int16_t args0 = stack[0].sval; | ||
| 241 | |||
| 242 | =head3 Getting int Type Argument | ||
| 243 | |||
| 244 | Use the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<int> type from an argument. | ||
| 245 | |||
| 246 | int32_t args0 = stack[0].ival; | ||
| 247 | |||
| 248 | =head3 Getting long Type Argument | ||
| 249 | |||
| 250 | Use the C<lval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<long> type from an argument. | ||
| 251 | |||
| 252 | int64_t args0 = stack[0].lval; | ||
| 253 | |||
| 254 | =head3 Getting float Type Argument | ||
| 255 | |||
| 256 | Use the C<fval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<float> type from an argument. | ||
| 257 | |||
| 258 | float args0 = stack[0].fval; | ||
| 259 | |||
| 260 | =head3 Getting double Type Argument | ||
| 261 | |||
| 262 | Use the C<dval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<double> type from an argument. | ||
| 263 | |||
| 264 | double args0 = stack[0].dval; | ||
| 265 | |||
| 266 | =head3 Getting Object Type Argument | ||
| 267 | |||
| 268 | Use the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM object type from an argument. | ||
| 269 | |||
| 270 | void* args0 = stack[0].oval; | ||
| 271 | |||
| 272 | =head3 Getting byte Reference Type Argument | ||
| 273 | |||
| 274 | Use the C<bref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<byte> reference type from an argument. | ||
| 275 | |||
| 276 | int8_t* args0 = stack[0].bref; | ||
| 277 | |||
| 278 | =head3 Getting short Reference Type Argument | ||
| 279 | |||
| 280 | Use the C<sref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<short> reference type from an argument. | ||
| 281 | |||
| 282 | int16_t* args0 = stack[0].sref; | ||
| 283 | |||
| 284 | =head3 Getting int Reference Type Argument | ||
| 285 | |||
| 286 | Use the C<iref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<int> reference type from an argument. | ||
| 287 | |||
| 288 | int32_t* args0 = stack[0].iref; | ||
| 289 | |||
| 290 | =head3 Getting long Reference Type Argument | ||
| 291 | |||
| 292 | Use the C<lref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<long> reference type from an argument. | ||
| 293 | |||
| 294 | int64_t* args0 = stack[0].lref; | ||
| 295 | |||
| 296 | =head3 Getting float Reference Type Argument | ||
| 297 | |||
| 298 | Use the C<fref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<float> reference type from an argument. | ||
| 299 | |||
| 300 | float* args0 = stack[0].fref; | ||
| 301 | |||
| 302 | =head3 Getting double Reference Type Argument | ||
| 303 | |||
| 304 | Use the C<dref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<double> reference type from an argument. | ||
| 305 | |||
| 306 | double* args0 = stack[0].dref; | ||
| 307 | |||
| 308 | =head3 Getting Multi-Numeric Type Arguments | ||
| 309 | |||
| 310 | The values of an SPVM multi-numeric type from an argument have been stored to the multiple values in L<runtime stack|/"Runtime Stack">. the length of the values in the runtime stack is the same as the length of the fields of the SPVM multi-numeric type. | ||
| 311 | |||
| 312 | For example, if the argument type is L<Complex_2d|SPVM::Complex_2d> type, these values have been stored to multiple fields the multiple values in the runtime stack. | ||
| 313 | |||
| 314 | double args0_re = stack[0].dval; | ||
| 315 | double args0_im = stack[1].dval; | ||
| 316 | |||
| 317 | =head2 Return Value | ||
| 318 | |||
| 319 | If the reutrn type of an SPVM method is not the C<void> type, the first argument of L<runtime stack|/"Runtime Stack"> must be set to a return value. | ||
| 320 | |||
| 321 | int32_t return_value = 5; | ||
| 322 | |||
| 323 | stack[0].ival = return_value; | ||
| 324 | |||
| 325 | =head3 Setting Return Value of byte Type | ||
| 326 | |||
| 327 | Use the C<bval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<byte> type. | ||
| 328 | |||
| 329 | stack[0].bval = return_value; | ||
| 330 | |||
| 331 | =head3 Setting Return Value of short Type | ||
| 332 | |||
| 333 | Use the C<sval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<short> type. | ||
| 334 | |||
| 335 | stack[0].sval = return_value; | ||
| 336 | |||
| 337 | =head3 Setting Return Value of int Type | ||
| 338 | |||
| 339 | Use the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<int> type. | ||
| 340 | |||
| 341 | stack[0].ival = return_value; | ||
| 342 | |||
| 343 | =head3 Setting Return Value of long Type | ||
| 344 | |||
| 345 | Use the C<lval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<long> type. | ||
| 346 | |||
| 347 | stack[0].lval = return_value; | ||
| 348 | |||
| 349 | =head3 Setting Return Value of float Type | ||
| 350 | |||
| 351 | Use the C<fval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<float> type. | ||
| 352 | |||
| 353 | stack[0].fval = return_value; | ||
| 354 | |||
| 355 | =head3 Setting Return Value of double Type | ||
| 356 | |||
| 357 | Use the C<dval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<double> type. | ||
| 358 | |||
| 359 | stack[0].dval = return_value; | ||
| 360 | |||
| 361 | =head3 Setting Return Value of Object Type | ||
| 362 | |||
| 363 | Use the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of an SPVM object type. | ||
| 364 | |||
| 365 | stack[0].oval = return_value; | ||
| 366 | |||
| 367 | =head3 Setting Return Value of Multi-Numeric Type | ||
| 368 | |||
| 369 | Multiple values in L<runtime stack|/"Runtime Stack"> are needed to be set to values of the field type of the multi-numeric type. The length of the values in the runtime stack is the same as the length of the fields of the SPVM multi-numeric type. | ||
| 370 | |||
| 371 | There is an example in the case that the return type is L<Complex_2d|SPVM::Complex_2d>. | ||
| 372 | |||
| 373 | double return_value_x; | ||
| 374 | double return_value_y; | ||
| 375 | stack[0].dval = return_value_x; | ||
| 376 | stack[1].dval = return_value_y; | ||
| 377 | |||
| 378 | =head2 Native APIs | ||
| 379 | |||
| 380 | L<Native APIs|SPVM::Document::NativeAPI> are the APIs written by the C language for SPVM operations. Native APIs can be called in native classes. | ||
| 381 | |||
| 382 | =head3 Examples of Native APIs | ||
| 383 | |||
| 384 | Create a Point object. | ||
| 385 | |||
| 386 | int32_t error_id = 0; | ||
| 387 | void* obj_point = env->new_object_by_name(env, stack, "Point", &error_id, __func__, FILE_NAME, __LINE__); | ||
| 388 | if (error_id) { return error_id; } | ||
| 389 | |||
| 390 | Call a class method. | ||
| 391 | |||
| 392 | int32_t error_id = 0; | ||
| 393 | int32_t total; | ||
| 394 | { | ||
| 395 | int32_t args_width = 2; | ||
| 396 | stack[0].ival = 5; | ||
| 397 | stack[1].ival = 10; | ||
| 398 | env->call_class_method_by_name(env, stack, "MyClass", "sum", args_width, &error_id, __func__, FILE_NAME, __LINE__); | ||
| 399 | if (error_id) { return error_id; } | ||
| 400 | |||
| 401 | total = stack[0].ival; | ||
| 402 | } | ||
| 403 | |||
| 404 | Get the characters of a string. | ||
| 405 | |||
| 406 | const char* chars = env->get_chars(env, stack, obj_string); | ||
| 407 | |||
| 408 | Get the elements of an array of int type. | ||
| 409 | |||
| 410 | int32_t* values = env->get_elems_int(env, stack, obj_array); | ||
| 411 | |||
| 412 | =head2 Exception | ||
| 413 | |||
| 414 | If a native method throws an exception, the native function must return a non-zero value, normally the basic type ID of an error class. | ||
| 415 | |||
| 416 | A message can be set to L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable">. If no message is set to L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable">, a default exception message is set to it. | ||
| 417 | |||
| 418 | env->set_exception(env, stack, env->new_string_nolen(env, stack, "An exception is thrown.")); | ||
| 419 | |||
| 420 | return SPVM_NATIVE_C_BASIC_TYPE_ID_ERROR_CLASS; | ||
| 421 | |||
| 422 | L<die|SPVM::Document::NativeAPI/"die"> native API can be used to throw an exception easily. | ||
| 423 | |||
| 424 | return env->die("The value must be %d.", __func__, FILE_NAME, __LINE__, 3); | ||
| 425 | |||
| 426 | =head2 Pointer Class | ||
| 427 | |||
| 428 | An SPVM object can have a L<pointer value|/"Pointer Value">. | ||
| 429 | |||
| 430 | If necessary, you can mark a class as a pointer class using L<pointer class attribute|SPVM::Document::Language::Class/"Class Attributes">. | ||
| 431 | |||
| 432 | class MyClass : pointer { | ||
| 433 | |||
| 434 | } | ||
| 435 | |||
| 436 | Examples of Pointer Classes: | ||
| 437 | |||
| 438 | C<SPVM/MyTm.spvm>: | ||
| 439 | |||
| 440 | class MyTm : pointer { | ||
| 441 | |||
| 442 | native static method new : MyTm (); | ||
| 443 | |||
| 444 | native method sec : int (); | ||
| 445 | |||
| 446 | native method DESTROY : (); | ||
| 447 | } | ||
| 448 | |||
| 449 | C<SPVM/MyTm.c>: | ||
| 450 | |||
| 451 | static const char* FILE_NAME = "MyTm.c"; | ||
| 452 | |||
| 453 | int32_t SPVM__MyTm__new(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 454 | |||
| 455 | int32_t error_id = 0; | ||
| 456 | |||
| 457 | strcut tm* st_tm = (struct tm*)env->new_memory_block(env, stack, sizeof (struct tm)); | ||
| 458 | |||
| 459 | void* obj_tm = env->new_object_by_name(env, stack, "MyTm", error_id, __func__, FILE_NAME, __LINE__); | ||
| 460 | if (error_id) { return error_id; } | ||
| 461 | |||
| 462 | env->set_pointer(env, stack, obj_tm, st_tm); | ||
| 463 | |||
| 464 | stack[0].oval = obj_tm; | ||
| 465 | |||
| 466 | return 0; | ||
| 467 | } | ||
| 468 | |||
| 469 | int32_t SPVM__MyTm__sec(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 470 | |||
| 471 | void* obj_tm = stack[0].oval; | ||
| 472 | |||
| 473 | strcut tm* st_tm = (struct tm*)env->get_pointer(env, stack, obj_tm); | ||
| 474 | |||
| 475 | stack[0].ival = st_tm->tm_sec; | ||
| 476 | |||
| 477 | return 0; | ||
| 478 | } | ||
| 479 | |||
| 480 | int32_t SPVM__MyTm__DESTROY(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 481 | |||
| 482 | void* obj_tm = stack[0].oval; | ||
| 483 | |||
| 484 | strcut tm* st_tm = (struct tm*)env->get_pointer(env, stack, obj_tm); | ||
| 485 | |||
| 486 | env->free_memory_block(env, stack, st_tm); | ||
| 487 | |||
| 488 | return 0; | ||
| 489 | } | ||
| 490 | |||
| 491 | =head3 Pointer Value | ||
| 492 | |||
| 493 | An object can have a pointer value. A pointer value is the address of a C/C++ object. | ||
| 494 | |||
| 495 | See L<get_pointer|SPVM::Document::NativeAPI/"get_pointer"> native API to get a pointer value of an object. | ||
| 496 | |||
| 497 | See L<set_pointer|SPVM::Document::NativeAPI/"set_pointer"> native API to set a pointer value of an object. | ||
| 498 | |||
| 499 | =head2 Native Directory | ||
| 500 | |||
| 501 | A native directory is the directory for native header files and native source files. | ||
| 502 | |||
| 503 | The name of the native directory is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.native>. | ||
| 504 | |||
| 505 | # The name of a native directory | ||
| 506 | SPVM/MyClass.native | ||
| 507 | |||
| 508 | =head3 Native Header Files | ||
| 509 | |||
| 510 | A native class can include native header files in the C<include> directory under the native directory. | ||
| 511 | |||
| 512 | # Native header files | ||
| 513 | SPVM/MyClass.native/include/foo.h | ||
| 514 | /dir/bar.h | ||
| 515 | |||
| 516 | // Native class | ||
| 517 | #include "foo.h" | ||
| 518 | #include "dir/bar.h" | ||
| 519 | |||
| 520 | =head3 Native Source Files | ||
| 521 | |||
| 522 | A native class can compile native source files in the C<src> directory under the native directory using L<add_source_file|SPVM::Builder::Config/"add_source_file"> in C<SPVM::Builder::Config> class. | ||
| 523 | |||
| 524 | # Native source files | ||
| 525 | SPVM/MyClass.native/src/foo.c | ||
| 526 | /dir/bar.c | ||
| 527 | |||
| 528 | # Native config file | ||
| 529 | my @source_files = ("foo.c", "dir/bar.c"); | ||
| 530 | $config->add_source_file(@source_files); | ||
| 531 | |||
| 532 | =head2 Scope | ||
| 533 | |||
| 534 | A native function has its scope. | ||
| 535 | |||
| 536 | L<enter_scope|SPVM::Document::NativeAPI/"enter_scope"> native API is called before the call of the native function. | ||
| 537 | |||
| 538 | L<leave_scope|SPVM::Document::NativeAPI/"leave_scope"> native API is called after the call of the native function. | ||
| 539 | |||
| 540 | You can create a scope and push objects to the L<native mortal stack|/"Native Mortal Stack">. | ||
| 541 | |||
| 542 | int32_t mortal_stack_top = env->enter_scope(env, stack); | ||
| 543 | |||
| 544 | env->push_mortal(env, stack, object); | ||
| 545 | |||
| 546 | env->leave_scope(env, stack, mortal_stack_top); | ||
| 547 | |||
| 548 | =head3 Native Mortal Stack | ||
| 549 | |||
| 550 | A mortal stack is created for a L<runtime stack|/"Runtime Stack">. | ||
| 551 | |||
| 552 | A mortal stack is the stack to save local variables to be destroyed at the end of the scope. | ||
| 553 | |||
| 554 | =head2 Runtime Environment | ||
| 555 | |||
| 556 | A runtime environement is created for an SPVM runtime. | ||
| 557 | |||
| 558 | This is the pointer to the value of C<SPVM_ENV> type, normally named C<env>. | ||
| 559 | |||
| 560 | SPVM_ENV* env; | ||
| 561 | |||
| 562 | A runtime environement is given to the first argument of a native function. | ||
| 563 | |||
| 564 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { | ||
| 565 | |||
| 566 | } | ||
| 567 | |||
| 568 | =head2 Runtime Stack | ||
| 569 | |||
| 570 | A runtime stack represents the execution context of an SPVM program. It is created for each native thread or coroutine. The SPVM runtime automatically creates a primary runtime stack for the main thread. | ||
| 571 | |||
| 572 | While it is named a "stack," it serves as a thread-local storage area that persists across function calls within the same execution unit. It is used to pass arguments to functions, receive return values, and store internal state specific to that thread, such as the L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable"> and caller information. | ||
| 573 | |||
| 574 | Technically, a runtime stack is a pointer to an array of L<SPVM_VALUE|/"SPVM_VALUE Type"> elements, and by convention, it is named C<stack>. | ||
| 575 | |||
| 576 | SPVM_VALUE* stack; | ||
| 577 | |||
| 578 | A runtime stack is passed as the second argument to all native functions: | ||
| 579 | |||
| 580 | int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { // ... } | ||
| 581 | |||
| 582 | You can manually manage runtime stacks for new threads or coroutines using the L<new_stack|SPVM::Document::NativeAPI/"new_stack"> and L<free_stack|SPVM::Document::NativeAPI/"free_stack"> native APIs. | ||
| 583 | |||
| 584 | =head3 Caller Stack | ||
| 585 | |||
| 586 | The B<caller stack> is a special region within the L<runtime stack|/"Runtime Stack"> used to store the history of method calls. It allows the runtime to trace back the execution path when an exception occurs or when debugging. | ||
| 587 | |||
| 588 | Each record in the caller stack consists of 4 elements (the record size is 4). | ||
| 589 | |||
| 590 | =over 2 | ||
| 591 | |||
| 592 | =item * 0: caller_method_abs_name (The absolute name of the caller method, such as C<Foo#bar> or C<SPVM__Foo__bar>) | ||
| 593 | |||
| 594 | =item * 1: caller_file (The file name of the caller) | ||
| 595 | |||
| 596 | =item * 2: caller_line (The line number of the caller) | ||
| 597 | |||
| 598 | =item * 3: current_method (The method currently being executed) | ||
| 599 | |||
| 600 | =back | ||
| 601 | |||
| 602 | Example: | ||
| 603 | |||
| 604 | // Get the current depth of the caller stack | ||
| 605 | int32_t call_depth = env->get_call_depth(env, stack); | ||
| 606 | |||
| 607 | // Get the raw pointer to the caller information stack | ||
| 608 | SPVM_VALUE* caller_info_stack = env->get_caller_info_stack(env, stack); | ||
| 609 | |||
| 610 | // Get the size of each record (Normally 4) | ||
| 611 | int32_t record_size = env->get_caller_info_stack_record_size(env, stack); | ||
| 612 | |||
| 613 | // Traverse the caller stack to build a backtrace | ||
| 614 | for (int32_t i = 0; i < call_depth; i++) { | ||
| 615 | SPVM_VALUE* record = &caller_info_stack[i * record_size]; | ||
| 616 | |||
| 617 | // Get caller information from the record | ||
| 618 | // caller_method_abs_name could be "Foo#bar" or "SPVM__Foo__bar" | ||
| 619 | const char* caller_method_abs_name = (const char*)record[0].address; | ||
| 620 | const char* caller_file = (const char*)record[1].address; | ||
| 621 | int32_t caller_line = record[2].ival; | ||
| 622 | |||
| 623 | // Get the current method information from the pointer | ||
| 624 | SPVM_NATIVE_METHOD* current_method = (SPVM_NATIVE_METHOD*)record[3].address; | ||
| 625 | const char* current_method_abs_name = env->api->method->get_abs_name(env->runtime, current_method); | ||
| 626 | |||
| 627 | // Process the information (e.g., printing a trace) | ||
| 628 | } | ||
| 629 | |||
| 630 | =head2 Arguments Width | ||
| 631 | |||
| 632 | The width of the arguments is the length in units of L<SPVM_VALUE|/"SPVM_VALUE Type"> type. | ||
| 633 | |||
| 634 | If the type is a multi-numeric type, the width of the arguments is the length of the fields of the multi-numeric type. Otherwise, it is 1. | ||
| 635 | |||
| 636 | Consider the following method definition. | ||
| 637 | |||
| 638 | method foo ($args0 : int, $args1 : Point, $arg2 : Complex_2d); | ||
| 639 | |||
| 640 | The argument width of the C<int> type is 1. | ||
| 641 | |||
| 642 | The argument width of the object type L<Point|SPVM::Point> is 1. | ||
| 643 | |||
| 644 | The argument width of the multi-numeric type L<Complex_2d|SPVM::Complex_2d> is the length of its field. It is 2. | ||
| 645 | |||
| 646 | So the width of the arguments is totally 4. | ||
| 647 | |||
| 648 | =head2 Native Motal Stack | ||
| 649 | |||
| 650 | A native mortal stack is a stack that is used by L<enter_scope|SPVM::Document::NativeAPI/"enter_scope"> native API and L<leave_scope|SPVM::Document::NativeAPI/"leave_scope"> native API. | ||
| 651 | |||
| 652 | A L<runtime stack|/"Runtime Stack"> has one native mortal stack. | ||
| 653 | |||
| 654 | =head2 Compilation and Link | ||
| 655 | |||
| 656 | A native class and native source files are compiled to object files and are linked and a shared library is generated. | ||
| 657 | |||
| 658 | The extension of a shared library is C<.so> in Linux and UNIX, C<.dylib> in Mac, C<.dll> in Windows. | ||
| 659 | |||
| 660 | Object files and a shared library file are output to the build directory. | ||
| 661 | |||
| 662 | If the L<SPVM_BUILD_DIR|SPVM::Document::EnvironmentVariables/"SPVM_BUILD_DIR"> environment variable is defined, it is used as the build directory. If it does not exist, it is created. | ||
| 663 | |||
| 664 | If the C<SPVM_BUILD_DIR> environment variable is not defined, a temporary directory is created at the beginning of the program, and the path is set to the environment variable. | ||
| 665 | |||
| 666 | |||
| 667 | Normally, C<~/.spvm_build> is used as the build directory. | ||
| 668 | |||
| 669 | # Example | ||
| 670 | export SPVM_BUILD_DIR=~/.spvm_build | ||
| 671 | |||
| 672 | =head2 Dependency Resolution | ||
| 673 | |||
| 674 | The dependencies of compilation and link of a L<native class|/"Native Class">, L<native header files|/"Native Header Files">, and L<native source files|/"Native Source Files"> are resolved by the following rules. | ||
| 675 | |||
| 676 | =over 2 | ||
| 677 | |||
| 678 | =item * If the version of SPVM is newer, the compilation and the link are performed. | ||
| 679 | |||
| 680 | =item * If the modification time of a native config file is newer than the generated dynamic library, the compilation and the link are performed. | ||
| 681 | |||
| 682 | =item * If the max of the modification time of the object files generated by compiliation is newer than the generated dynamic library, the link is performed. | ||
| 683 | |||
| 684 | =item * If the modification time of a native class is newer than the object file generated from the native class, the compilation is performed. | ||
| 685 | |||
| 686 | =item * If the modification time of a native source file is newer than the generated object file, the compilation is performed. | ||
| 687 | |||
| 688 | =item * If the max of the modification time of header source files is newer than the object file generated from a native source file, the compilation of the native source file is performed. | ||
| 689 | |||
| 690 | =back | ||
| 691 | |||
| 692 | =head1 Native Types | ||
| 693 | |||
| 694 | These types are used in the Native API. | ||
| 695 | |||
| 696 | If C<SPVM_NATIVE_TYPE_STRICT> is defined, these types are defined as pointer types to opaque structures for strict type checking. Otherwise, they are defined as C<void>. | ||
| 697 | |||
| 698 | =head2 SPVM_NATIVE_ALLOCATOR | ||
| 699 | |||
| 700 | The native type for the allocator. See L<SPVM::Document::NativeAPI::Allocator>. | ||
| 701 | |||
| 702 | =head2 SPVM_NATIVE_STRING_BUFFER | ||
| 703 | |||
| 704 | The native type for the string buffer. See L<SPVM::Document::NativeAPI::StringBuffer>. | ||
| 705 | |||
| 706 | =head2 SPVM_NATIVE_COMPILER | ||
| 707 | |||
| 708 | The native type for the compiler. See L<SPVM::Document::NativeAPI::Compiler>. | ||
| 709 | |||
| 710 | =head2 SPVM_NATIVE_CLASS_FILE | ||
| 711 | |||
| 712 | The native type for the class file. See L<SPVM::Document::NativeAPI::ClassFile>. | ||
| 713 | |||
| 714 | =head2 SPVM_NATIVE_RUNTIME | ||
| 715 | |||
| 716 | The native type for the runtime. See L<SPVM::Document::NativeAPI::Runtime>. | ||
| 717 | |||
| 718 | =head2 SPVM_NATIVE_BASIC_TYPE | ||
| 719 | |||
| 720 | The native type for the basic type. See L<SPVM::Document::NativeAPI::BasicType>. | ||
| 721 | |||
| 722 | =head2 SPVM_NATIVE_CLASS_VAR | ||
| 723 | |||
| 724 | The native type for the class variable. See L<SPVM::Document::NativeAPI::ClassVariable>. | ||
| 725 | |||
| 726 | =head2 SPVM_NATIVE_FIELD | ||
| 727 | |||
| 728 | The native type for the field. See L<SPVM::Document::NativeAPI::Field>. | ||
| 729 | |||
| 730 | =head2 SPVM_NATIVE_METHOD | ||
| 731 | |||
| 732 | The native type for the method. See L<SPVM::Document::NativeAPI::Method>. | ||
| 733 | |||
| 734 | =head2 SPVM_NATIVE_ARG | ||
| 735 | |||
| 736 | The native type for the argument. See L<SPVM::Document::NativeAPI::Argument>. | ||
| 737 | |||
| 738 | =head2 SPVM_NATIVE_MUTEX | ||
| 739 | |||
| 740 | The native type for the mutex. See L<SPVM::Document::NativeAPI::Mutex>. | ||
| 741 | |||
| 742 | =head2 SPVM_NATIVE_OPCODE | ||
| 743 | |||
| 744 | The native type for the opcode. | ||
| 745 | |||
| 746 | =head2 SPVM_OBJ | ||
| 747 | |||
| 748 | The native type for the SPVM object. See L<SPVM::Document::NativeClass>. | ||
| 749 | |||
| 750 | =head2 SPVM_REF | ||
| 751 | |||
| 752 | The native type for the SPVM reference. | ||
| 753 | |||
| 754 | =head1 Resource | ||
| 755 | |||
| 756 | A native class can use native header files and native source files writen by native langauges such as the C language and C++ using L<SPVM::Builder::Config#use_resource|SPVM::Builder::Config/"use_resource">. | ||
| 757 | |||
| 758 | # MyClass.build | ||
| 759 | $config->use_resource("Resource::Zlib"); | ||
| 760 | |||
| 761 | // MyClass.c | ||
| 762 | #include "zlib.h" | ||
| 763 | |||
| 764 | For details, see L<SPVM::Document::Resource>. | ||
| 765 | |||
| 766 | =head1 Distribution | ||
| 767 | |||
| 768 | A distribution for a native class can be generated by L<spvmdist> command. | ||
| 769 | |||
| 770 | # C | ||
| 771 | spvmdist --native c --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass | ||
| 772 | |||
| 773 | # C++ | ||
| 774 | spvmdist --native c++ --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass | ||
| 775 | |||
| 776 | A native class file and a config file only can be added to an existing distribution. | ||
| 777 | |||
| 778 | # C | ||
| 779 | spvmdist --only-lib-files --native c --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass lib | ||
| 780 | |||
| 781 | # C++ | ||
| 782 | spvmdist --only-lib-files --native c++ --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass lib | ||
| 783 | |||
| 784 | =over 2 | ||
| 785 | |||
| 786 | =item * L<spvmdist> | ||
| 787 | |||
| 788 | =back | ||
| 789 | |||
| 790 | =head1 See Also | ||
| 791 | |||
| 792 | =head2 Documents | ||
| 793 | |||
| 794 | =over 2 | ||
| 795 | |||
| 796 | =item * L<SPVM::Document::Language::Class> | ||
| 797 | |||
| 798 | =item * L<SPVM::Document> | ||
| 799 | |||
| 800 | =back | ||
| 801 | |||
| 802 | =head2 Config | ||
| 803 | |||
| 804 | =over 2 | ||
| 805 | |||
| 806 | =item * L<SPVM::Builder::Config> | ||
| 807 | |||
| 808 | =item * L<SPVM::Builder::Config::Exe> | ||
| 809 | |||
| 810 | =back | ||
| 811 | |||
| 812 | =head2 Native APIs | ||
| 813 | |||
| 814 | =over 2 | ||
| 815 | |||
| 816 | =item * L<SPVM::Document::NativeAPI> | ||
| 817 | |||
| 818 | =item * L<SPVM::Document::NativeAPI::Method> | ||
| 819 | |||
| 820 | =item * L<SPVM::Document::NativeAPI::ClassVariable> | ||
| 821 | |||
| 822 | =item * L<SPVM::Document::NativeAPI::Allocator> | ||
| 823 | |||
| 824 | =item * L<SPVM::Document::NativeAPI::Compiler> | ||
| 825 | |||
| 826 | =item * L<SPVM::Document::NativeAPI::Internal> | ||
| 827 | |||
| 828 | =item * L<SPVM::Document::NativeAPI::Mutex> | ||
| 829 | |||
| 830 | =item * L<SPVM::Document::NativeAPI::Field> | ||
| 831 | |||
| 832 | =item * L<SPVM::Document::NativeAPI::BasicType> | ||
| 833 | |||
| 834 | =item * L<SPVM::Document::NativeAPI::Runtime> | ||
| 835 | |||
| 836 | =item * L<SPVM::Document::NativeAPI::Type> | ||
| 837 | |||
| 838 | =item * L<SPVM::Document::NativeAPI::StringBuffer> | ||
| 839 | |||
| 840 | =item * L<SPVM::Document::NativeAPI::ModuleFile> | ||
| 841 | |||
| 842 | =item * L<SPVM::Document::NativeAPI::ClassFile> | ||
| 843 | |||
| 844 | =item * L<SPVM::Document::NativeAPI::Argument> | ||
| 845 | |||
| 846 | =item * L<Examples using native methods|https://github.com/yuki-kimoto/SPVM/tree/master/examples/native> | ||
| 847 | |||
| 848 | =back | ||
| 849 | |||
| 850 | =head2 Resource | ||
| 851 | |||
| 852 | =over 2 | ||
| 853 | |||
| 854 | =item * L<SPVM::Document::Resource> | ||
| 855 | |||
| 856 | =back | ||
| 857 | |||
| 858 | =head1 Copyright & License | ||
| 859 | |||
| 860 | Copyright (c) 2023 Yuki Kimoto | ||
| 861 | |||
| 862 | MIT License |