Changes between Initial Version and Version 1 of PCCMigrationNotes

Show
Ignore:
Timestamp:
11/03/09 19:11:27 (5 years ago)
Author:
allison
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PCCMigrationNotes

    v1 v1  
     1This page provides some details on migrating external code to use the new Parrot calling conventions implementation. The core focus of this change was to move all sub or method calls throughout the system to store their arguments and returns in a CallSignature PMC, instead of various different ways depending on how the sub/method was called (varargs list, call state struct, direct pointer to the memory location of the opcode where the args were passed, in the interpreter structure, etc). 
     2 
     3== PIR/PASM/PBC interface == 
     4 
     5Unchanged. The opcodes for sub and method calls are the same, called in the same order. The PIR syntactic sugar for sub and method calls is the same. (This is to meet the Parrot support policy, there will be some small changes to the opcode order after 2.0.) 
     6 
     7== C API Functions == 
     8 
     9The following functions have been preserved for backward compatibility with the existing defined C API. The internals of the functions have been completely replaced, but they exactly preserve the old interface, including accepting only old-style signature strings (with the return value type as the first character in the string).  
     10 
     11{{{ 
     12src/extend.c: 
     13  Parrot_call_sub 
     14  Parrot_call_sub_ret_int 
     15  Parrot_call_sub_ret_float 
     16  Parrot_call_method 
     17  Parrot_call_method_ret_int 
     18  Parrot_call_method_ret_float 
     19}}} 
     20 
     21These functions are only preserved for backward compatibility under the support policy, and have been deprecated to be removed after 2.0. (See TT #1145.) The replacement function is 'Parrot_ext_call', and it handles all the cases that the previous set of functions handled. (Recommended to go ahead and migrate to the new function, even though the old functions will be around until 2.0.) 
     22 
     23'Parrot_ext_call' takes a new-style signature string, where the return value type(s) are listed at the end of the signature, separated from the args by an arrow ('->'). The variables for the return values to be stored in are also passed as references after all the arguments in the call. (See the documentation for 'Parrot_ext_call' for more details.) 
     24 
     25{{{ 
     26INTVAL result; 
     27Parrot_ext_call(interp, cmp, "PP->I", a, b, &result); 
     28return result; 
     29}}} 
     30 
     31The following functions have been deprecated and removed. Calls to any of these functions can be replaced by a call to 'Parrot_ext_call' (with an appropriate signature string). 
     32 
     33{{{ 
     34src/call/ops.c: 
     35  runops_args 
     36  Parrot_run_meth_fromc 
     37  Parrot_runops_fromc_args 
     38  Parrot_runops_fromc_args_event 
     39  Parrot_runops_fromc_args_reti 
     40  Parrot_runops_fromc_args_retf 
     41  Parrot_run_meth_fromc_args 
     42  Parrot_run_meth_fromc_args_reti 
     43  Parrot_run_meth_fromc_args_retf 
     44  Parrot_runops_fromc_arglist 
     45  Parrot_runops_fromc_arglist_reti 
     46  Parrot_runops_fromc_arglist_retf 
     47  Parrot_run_meth_fromc_arglist 
     48  Parrot_run_meth_fromc_arglist_reti 
     49  Parrot_run_meth_fromc_arglist_retf 
     50}}} 
     51 
     52The following functions have been deprecated and removed. They were only used internally, so shouldn't require migration, but if you were using them for any reason, there's a good chance you'll what to move to 'Parrot_ext_call' instead. 
     53 
     54{{{ 
     55src/call/pcc.c: 
     56  parrot_pass_args 
     57  parrot_pass_args_fromc 
     58  Parrot_init_ret_nci 
     59  Parrot_init_arg_nci 
     60}}} 
     61 
     62'parrot_pass_args' has been replaced by 'Parrot_pcc_fill_params_from_op', and 'parrot_pass_args_fromc' has been replaced by 'Parrot_pcc_fill_params_from_c_args'. 
     63 
     64The following functions will be deprecated in the future: 
     65 
     66{{{ 
     67src/call/pcc.c: 
     68  Parrot_pcc_invoke_sub_from_c_args 
     69  Parrot_PCCINVOKE 
     70}}} 
     71 
     72'Parrot_pcc_invoke_sub_from_c_args' is exactly the same as 'Parrot_ext_call', but with a worse name, so use 'Parrot_ext_call' instead. 'Parrot_PCCINVOKE' is exactly the same as 'Parrot_pcc_invoke_method_from_c_args', but with a worse name. (See TT #443.) 
     73 
     74== Other C API pieces == 
     75 
     76The interpreter structure no longer has 'interp->current_args', 'interp->current_params', 'interp->current_returns', 'interp->args_signature', 'interp->params_signature', or 'interp->returns_signature' elements. The closest equivalent is 'CURRENT_CONTEXT(interp)->current_sig' (that is, the 'current_sig' element of the current context) which is the CallSignature PMC for the current call (and contains the arguments and results). Don't access this struct element directly, use the interface functions 'Parrot_pcc_get_signature' and 'Parrot_pcc_set_signature' instead. 
     77 
     78{{{ 
     79PMC * const this_call_sig   = Parrot_pcc_get_signature(interp, ctx); 
     80}}} 
     81 
     82The 'interp->current_object' element still exists, but will go away once we merge all calls to store the object for method invocations in the CallSignature. (Certain parts of IMCC were left unchanged for now.) 
     83 
     84== Testing == 
     85 
     86Added a 'throws_substring' test function to Test::More, to capture inexact exception messages without depending on PGE in the core tests.