Author: allison
Date: Tue Feb 27 13:48:38 2007
New Revision: 17209
Modified:
trunk/docs/pdds/draft/pdd16_native_call.pod
Log:
[pdd]: Some cleanups and a callback example for NCI PDD. Klaas-Jan
Stol++
Modified: trunk/docs/pdds/draft/pdd16_native_call.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd16_native_call.pod (original)
+++ trunk/docs/pdds/draft/pdd16_native_call.pod Tue Feb 27 13:48:38 2007
@@ -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,68 @@
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
+
+ .local pmc sub, userdata
+ sub = get_global "foo_callback" # get the sub to act as a callback sub
+
+ userdata = new .Integer # set up some userdata
+ userdata = 42
+
+ .local pmc callback_sub
+ callback_sub = new_callback sub, userdata, "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 +325,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,34 +335,21 @@
=over 4
-=item version 1.2
-
-Updated with basic example.
+=item version 1.3
-=item version 1.1
-
-Changed callback section to reflect current status.
-
-=item version 1
-
-None. First version
-
-=back
-
-=head1 CHANGES
-
-=over 4
+Updated with example for callbacks
=item version 1.2
-Updated with basic example.
+Updated with basic example for NCI.
=item version 1.1
Changed callback section to reflect current status.
-=item Version 1.0
+=item version 1
None. First version
=back
+
