cvsuser 04/10/12 04:18:13
Modified: docs/pdds pdd16_native_call.pod
Log:
update callback pod
Revision Changes Path
1.12 +43 -65 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.11
retrieving revision 1.12
diff -u -w -r1.11 -r1.12
--- pdd16_native_call.pod 17 Aug 2004 09:16:18 -0000 1.11
+++ pdd16_native_call.pod 12 Oct 2004 11:18:12 -0000 1.12
@@ -1,5 +1,5 @@
# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
-# $Id: pdd16_native_call.pod,v 1.11 2004/08/17 09:16:18 leo Exp $
+# $Id: pdd16_native_call.pod,v 1.12 2004/10/12 11:18:12 leo Exp $
=head1 NAME
@@ -119,36 +119,11 @@
string pointer. Taken from, or stuck into, a string
register. (Converted to a null-terminated C string before passing in)
-=item C
-
-This parameter is used for passing in a callback function pointer. It
-refers to the function Parrot_callback_C, which has a signature of:
-
- void Parrot_callback_C(void *external_data, PMC *callback_info);
-
-More explanation in the L<callbacks> section.
-
-=item D
-
-This parameter is used for passing in a callback function pointer. It
-refers to the function Parrot_callback_C, which has a signature of:
-
- void Parrot_callback_D(PMC *callback_info, void *external_data);
+=item U
+This parameter is used for passing user data to a callback creation.
More explanation in the L<callbacks> section.
-=item Y
-
-This parameter is a PMC for the sub which should be called into by
-the callback. Only valid in a signature with a C or D parameter, and
-it I<must> be immediately followed by a parameter of type Z.
-
-=item Z
-
-This parameter is a PMC representing the data to be passed into the
-function being called into. It is only valid when it immediately
-follows a parameter of type Y.
-
=back
Note that not all types are valid as return types.
@@ -173,36 +148,40 @@
purpose that should serve for most of the callback uses.
There are two callback functions, Parrot_callback_C and
-Parrot_callback_D, corresponding to callback function signature
-letters C and D, respectively. If the callback function is supposed
-to look like:
+Parrot_callback_D, which differ if the passed in C<user_data> is
+second or first respectively:
+
+ void (function *)(void *library_data, void *user_data);
+
+ void (function *)(void *user_data, void *library_data);
- void (function *)(void *library_data, void *your_data);
+The information C<library_data> is normally coming from C code and
+can be any C type that Parrot supports as NCI value.
-then use type C, where if the function signature is:
+The position of the C<user_data> is specified with the C<U> function
+signature, when creating the callback PMC:
- void (function *)(void *your_data, void *library_data);
+ cb_PMC = new_callback cb_Sub, user_data, "tU"
-then use a type of D. The actual pointer types for the parameters
-don't have to be void *, but they must be pointers of some sort.
+Given a Parrot function C<cb_Sub>, and a C<user_data> PMC, this creates
+a callback PMC C<cb_PMC>, which expects the user data as the second argument.
+The information returned by the callback (C<library_data) is a C string.
Since parrot needs more than just a pointer to a generic function to
figure out what to do, it stuffs all the extra information into the
-C<your_data> pointer, which contains a custom PMC holding all the
-information that Parrot needs.
+C<user_data> pointer, which contains a custom PMC holding all the
+information that Parrot needs. This also implies that the C function
+that installs the callback, must not make any assumptions on the C<user_data>
+argument. This argument must be handled transparently by the C code.
-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>.
-
-The callback functions take care of wrapping the external data
+The callback function takes 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)
+ void parrotsub(PMC user_data, <type> external_data)
The sequence for this is:
@@ -210,29 +189,16 @@
=item Step 1
-Register the function which takes all the callback information
+Create a callback function.
- dlfunc CALLBACK_REGISTER_FUNC, LIBRARY_PMC, FUNCTION_NAME, 'vCYZ'
+ new_callback CB_PMC, CB_SUB, USER_DATA, "signature"
=item Step 2
-Register the actual callback
+Register the 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!>
+ dlfunc C_FUNCION, "function_name", "signature"
+ C_FUNCTION(CP_PMC, USER_DATA)
=back
@@ -241,7 +207,7 @@
.sub _my_callback prototyped
.param pmc my_data
- .param pmc library_data
+ .param pmc library_data # type depends on signature
# Do something with the passed in data
.end
@@ -253,6 +219,10 @@
L<pdd06_pasm.pod>
+=head1 SEE ALSO
+
+L<t/pmc/nci.t>, L<src/nci_test.c>
+
=head1 VERSION
=head2 CURRENT
@@ -260,9 +230,9 @@
Maintainer: Dan Sugalski
Class: Internals
PDD Number: 16
- Version: 1.0
+ Version: 1.1
Status: Developing
- Last Modified: December 28, 2003
+ Last Modified: Oct 12, 2004
PDD Format: 1
Language: English
@@ -270,6 +240,10 @@
=over 4
+=item version 1.1
+
+Changed callback section to reflect current status.
+
=item version 1
None. First version
@@ -280,6 +254,10 @@
=over 4
+=item version 1.1
+
+Changed callback section to reflect current status.
+
=item Version 1.0
None. First version
