hi,
I've been playing with NCI calls and more fun (embedding a Parrot, that
runs a PIR program, which invokes a C function, that then invokes a PIR
callback function).
As a result, I added a simple example to PDD16. I didnt' put too much
work in it (there are many more places that could be improved), because
I didn't know if updating this doc is desirable at this moment (any big
changes pending?).
If desired, I'd be happy to do more updates. Please let me know.
At least there's full working code to do a simple NCI invocation.
regards,
klaas-jan
Index: docs/pdds/draft/pdd16_native_call.pod
===================================================================
--- docs/pdds/draft/pdd16_native_call.pod (revision 17146)
+++ docs/pdds/draft/pdd16_native_call.pod (working copy)
@@ -126,8 +126,48 @@
=head2 Examples
Most of the function parameters are reasonably self-evident. Some, however,
-merit additional explanation. The {{ ??? }}
+merit additional explanation.
+This section describes the simplest example for NCI possible. To every NCI
+invocation, there are two parts: the native function to be invoked, and the
+PIR code to do the invocation.
+
+First the native function, to be written in C.
+On Windows, it is necessary to do a DLL export specification of the NCI function:
+
+ /* foo.c */
+
+ /* specify the function prototype */
+
+ void foo(void);
+
+ /* or on Windows using Microsoft Visual Studio: */
+
+ __declspec(dllexport) void foo(void);
+
+ void foo(void) {
+ printf("Hello Parrot!\n");
+ }
+
+Then, after having compiled the file as a shared library, the PIR code looks
+like this:
+
+ .sub main :main
+ .local pmc lib, func
+
+ # load the shared library
+ lib = loadlib "hello" # no extension, .so or .dll is assumed
+
+ # get a reference to the function from the library just
+ # loaded, called "foo", and signature "void" (and no arguments)
+ func = dlfunc lib, "foo", "v"
+
+ # invoke
+ func()
+
+ .end
+
+
=head2 Callbacks
Some libraries, particularly ones implementing more complex functionality such
@@ -224,9 +264,9 @@
Maintainer: Dan Sugalski
Class: Internals
PDD Number: 16
- Version: 1.1
+ Version: 1.2
Status: Developing
- Last Modified: Oct 12, 2004
+ Last Modified: Feb 23, 2007
PDD Format: 1
Language: English
@@ -234,6 +274,10 @@
=over 4
+=item version 1.2
+
+Updated with basic example.
+
=item version 1.1
Changed callback section to reflect current status.
@@ -248,6 +292,10 @@
=over 4
+=item version 1.2
+
+Updated with basic example.
+
=item version 1.1
Changed callback section to reflect current status.
