hi,
I made some additional changes to PDD16:
* added an example to do a callback. I left in the "old" explanation,
but Im' not sure how much of that is still relevant.
* small text improvements wrt example nci
* removed "CHANGES" section: it was just duplicating the history
section. This PDD does *not* follow the standard as set in PDD00 anyway,
that should be looked into once the PDD is in the approval process.
regards,
kjs
Index: docs/pdds/draft/pdd16_native_call.pod
===================================================================
--- docs/pdds/draft/pdd16_native_call.pod (revision 17188)
+++ docs/pdds/draft/pdd16_native_call.pod (working copy)
@@ -123,7 +123,7 @@
Note that not all types are valid as return types.
-=head2 Examples
+=head2 Example NCI call
Most of the function parameters are reasonably self-evident. Some, however,
merit additional explanation.
@@ -138,12 +138,11 @@
/* foo.c */
/* specify the function prototype */
-
- void foo(void);
-
- /* or on Windows using Microsoft Visual Studio: */
-
+ #ifdef __WIN32
__declspec(dllexport) void foo(void);
+ #else
+ void foo(void);
+ #endif
void foo(void) {
printf("Hello Parrot!\n");
@@ -239,7 +238,7 @@
When the callback function is invoked by the external library, the function
itself should look like:
- .sub _my_callback prototyped
+ .sub _my_callback
.param pmc my_data
.param pmc library_data # type depends on signature
# Do something with the passed in data
@@ -249,6 +248,67 @@
interpreter pointer, creating the wrapping PMCs, stuffing data various places,
and generally dealing with the bookkeeping.
+=head2 Example Callback
+
+This section contains an example to register a callback function and have
+it call back into Parrot.
+
+ .sub main
+
+ # set up callback
+
+ $P0 = get_global "foo_callback" # get the sub to act as a callback sub
+
+ $P1 = new .Integer # set up some userdata
+ $P1 = 42
+
+ .local pmc callback_sub
+ callback_sub = new_callback $P0, $P1, "vtU"
+
+ # set up NCI
+
+ .local pmc lib, fun
+ lib = loadlib "hello"
+ fun = dlfunc lib, "sayhello", "vpP"
+
+ # do the NCI call, foo_callback is invoked from C
+ fun()
+
+ .end
+
+ .sub foo_callback
+ .param pmc result
+ .param pmc udata
+ print "Foo callback\n"
+ .end
+
+The C code contains the function to be invoked through NCI. In the function C<sayhello>
+a function call is done to a Parrot subroutine. The C<sayhello> function gets a reference
+to this callback function, so its signature needs to be known.
+
+ #include <stdio.h>
+ #include <parrot/parrot.h>
+
+ /* declare the function signature of the Parrot sub that will be invoked */
+ typedef void (*callbackfun)(const char*, void*);
+
+ #ifdef __WIN32
+ __declspec(dllexport) void sayhello(callbackfun cb, void *userdata);
+ #else
+ void sayhello(callbackfun cb, void *userdata);
+ #endif
+
+ void sayhello(callbackfun cb, void* userdata) {
+ const char *result = "succeeded";
+
+ /* invoke the callback synchronously */
+ cb(result, userdata);
+ }
+
+The file containing this C code should be compiled as a shared library (specifying the C<include> directory so
+C<<parrot/parrot.h>> can be found.)
+
+
=head1 REFERENCES
L<pdd06_pasm.pod>
@@ -264,9 +324,9 @@
Maintainer: Dan Sugalski
Class: Internals
PDD Number: 16
- Version: 1.2
+ Version: 1.3
Status: Developing
- Last Modified: Feb 23, 2007
+ Last Modified: Feb 26, 2007
PDD Format: 1
Language: English
@@ -274,9 +334,13 @@
=over 4
+=item version 1.3
+
+Updated with example for callbacks
+
=item version 1.2
-Updated with basic example.
+Updated with basic example for NCI.
=item version 1.1
@@ -288,20 +352,3 @@
=back
-=head1 CHANGES
-
-=over 4
-
-=item version 1.2
-
-Updated with basic example.
-
-=item version 1.1
-
-Changed callback section to reflect current status.
-
-=item Version 1.0
-
-None. First version
-
-=back
