cvsuser 03/12/28 13:08:33
Modified: docs/pdds pdd16_native_call.pod Log: callback section done Revision Changes Path 1.3 +55 -1 parrot/docs/pdds/pdd16_native_call.pod Index: pdd16_native_call.pod =================================================================== RCS file: /cvs/public/parrot/docs/pdds/pdd16_native_call.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -w -r1.2 -r1.3 --- pdd16_native_call.pod 28 Dec 2003 20:59:51 -0000 1.2 +++ pdd16_native_call.pod 28 Dec 2003 21:08:33 -0000 1.3 @@ -157,7 +157,61 @@ The NCI function signature for a callback matching Parrot_callback_C is C<vCYZ>, while the function signature for a callback matching -Parrot_callback_D is C<vDYZ> +Parrot_callback_D is C<vDYZ>. + +The callback functions take care of wrapping the external data +pointer into an UnManagedStruct PMC, the same as if it were a p +return type of a normal NCI function. + +The signature of the I<parrot> subroutine which is called by the +callback should be: + + void parrotsub(PMC user_data, PMC external_data) + +The sequence for this is: + +=over 4 + +=item Step 1 + +Register the function which takes all the callback information + + dlfunc CALLBACK_REGISTER_FUNC, LIBRARY_PMC, FUNCTION_NAME, 'vCYZ' + +=item Step 2 + +Register the actual callback + + newsub $P5, .Sub, _some_parrot_sub + # Alternately, if it's in a global + # $P5 = global "some::sub::name" + new $P6, .PerlInt # The data we get handed + .pcc_begin prototyped + .arg $P5 + .arg $P6 + .pcc_call CALLBACK_REGISTER_FUNC + .pcc_end + +=item Step 3 + +Hand over control to the external library. I<IT IS IMPORTANT THAT THE +INTERPRETER YOU ARE CALLING BACK INTO IS NOT ACTIVE WHEN THE CALLBACK +IS MADE!> + +=back + +When the callback function is invoked by the external library, the +function itself should look like: + + .sub _my_callback prototyped + .param pmc my_data + .param pmc library_data + # Do something with the passed in data + .end + +Parrot itself handles all the nasty bits involved in collecting up +the interpreter pointer, creating the wrapping PMCs, stuffing data +various places, and generally dealing with the bookkeeping. =head1 REFERENCES
