Tutorial question - perldoc perlxs - learning how to write XS-basedcode

[Dilbert]

I have been using swig http://www.swig.org/ to incorporate simple C
subroutines into my Perl programs. That works fine, no complaint at
all.

However, I would now like to get my hands dirty and learn how to
communicate between Perl and C from the bottom up using XS-code.

I am thinking about reading "perldoc perlxs", but before I embark on
that adventure, I would ask for your oppinion:

- Would you recommed reading "perldoc perlxs" ?
- Are there any other tutorials ?

For example, if I wrote a C-function

first_test(int i, double d, char* s)

that returns a list -- three values:

* the first value is i - 1234
* the second value is d / 4.2
* the third value is a string "<".s.">".

My first beginner questions would be like:

- How do parameters get passed into the C-function ?
- What happens if Perl gives a string, but the C-function expects a
double ?
- What happens if Perl gives a double, but the C-function expects a
string ?
- How can a C-function return a list of values ?
- Do I need to allocate (malloc ?) memory to return values ?
- Who is reponsible for garbage collections of the allocated memory ?
- Can I pass / return more complicated data structures (hashes of
hashes, lists of lists, etc...) ?

Many questions, but I don't expect an immediate answer. What I really
want to know is: what would be the best tutorial for me ?

 

[Dilbert]

I am thinking about reading "perldoc perlxs"

[answering my own question]
"perldoc perlxstut" seems to be what I want -- stupid me, I didn't see
the obvious

I think I will start with "perldoc perlxstut", but if anybody knows of
other good tutorials about writing XS code, I am happy to add them to
my list.

 

[sln]

I have been using swig http://www.swig.org/ to incorporate simple C
subroutines into my Perl programs. That works fine, no complaint at
all.

However, I would now like to get my hands dirty and learn how to
communicate between Perl and C from the bottom up using XS-code.

I am thinking about reading "perldoc perlxs", but before I embark on
that adventure, I would ask for your oppinion:

- Would you recommed reading "perldoc perlxs" ?
- Are there any other tutorials ?

For example, if I wrote a C-function

first_test(int i, double d, char* s)

that returns a list -- three values:

* the first value is i - 1234
* the second value is d / 4.2
* the third value is a string "<".s.">".

My first beginner questions would be like:

- How do parameters get passed into the C-function ?
- What happens if Perl gives a string, but the C-function expects a
double ?
- What happens if Perl gives a double, but the C-function expects a
string ?
- How can a C-function return a list of values ?
- Do I need to allocate (malloc ?) memory to return values ?
- Who is reponsible for garbage collections of the allocated memory ?
- Can I pass / return more complicated data structures (hashes of
hashes, lists of lists, etc...) ?

Many questions, but I don't expect an immediate answer. What I really
want to know is: what would be the best tutorial for me ?

I would imagine Perl is written in C, where there is no stateless types.
Every thing is a strict type: ptr, int (32/16/8), char, struct, enum,union and
(...), etc. This is done to partition (format) memory, stack or otherwise.
Passing/returning data/value to/from functions follow ANSI C standards.
Some of your questions are on this level. For the answers to these questions,
you should learn C before you attempt xs interface.

-sln

 

[Dilbert]

[ snip ]

For example, if I wrote a C-function
  first_test(int i, double d, char* s)
that returns a list -- three values:
 * the first value is i - 1234
 * the second value is d / 4.2
 * the third value is a string "<".s.">".

You don't. You write an XSUB, which is then converted into a C function
by xsubpp.

My first beginner questions would be like:
 - How do parameters get passed into the C-function ?

The generated bits handle pulling the parameters off the perl stack and
putting them in C locals.

 - What happens if Perl gives a string, but the C-function expects a
double ?
 - What happens if Perl gives a double, but the C-function expects a
string ?

Since xsubpp knows the types the function is expecting, it will
auto-convert in the usual way. (This includes, for example, calling
stingification on an overloaded object.) This process can be controlled
using a 'typemap' (see perlxs), or you can write your XSUB to take SV *
parameters instead and extract the value you want by hand.

 - How can a C-function return a list of values ?

By using the supplied macros to push the list onto the perl stack.

 - Do I need to allocate (malloc ?) memory to return values ?

Yes, but you should do so through the perl API.

 - Who is reponsible for garbage collections of the allocated memory ?

You are responsible for getting refcounts right. Perl will
garbage-collect any SVs that go out of scope; you are responsible for
writing a DESTROY method (or using magic) to make sure any other memory
you've allocated gets freed. Perl doesn't have any system like Apache's
pools, where you can allocate stuff and forget about it; nor does it
have a true garbage collector.

 - Can I pass / return more complicated data structures (hashes of
hashes, lists of lists, etc...) ?

Yes. It's a little awkward until you get used to it, but the perl API
matches the operations you would perform in Perl pretty well. The most
annoying part is having to do things one at a time: instead of writing

    return [1, 2, {a => "b"}];

you have to write something like (this is from memory, so might be
incorrect)

    AV *av, HV *hv;

    av = newAV();
    RETVAL = newRV_noinc(av);

    av_push(av, newSViv(1));
    av_push(av, newSViv(2));

    hv = newHV();
    av_push(av, newRV_noinc(hv));

    hv_stores(hv, "a", newSVpvs("b"));

Every line there performs an allocation, all of which will be freed when
the SV in RETVAL goes out of scope. (RETVAL is a special local variable
which is the simplest way of returning a scalar result from an XSUB.)

Many questions, but I don't expect an immediate answer. What I really
want to know is: what would be the best tutorial for me ?

perlxstut would be a good place to start. After that you need to read
perlxs, perlapi and perlguts, even if you don't understand it all right
away.

Thanks for all your help, this is much appreciated and will get me
started on my journey.