I am starting a personal project to build a Perl API for a C library whose source is not available but headers and the shared library are. After some good advice here, and some largely unsuccessful attempts at understanding the XS docs, I have decided to begin from a simpler starting point - Inline::C and then re-attempt XS once I understand perlguts and the perlapi better. I want to reach that better understanding in 3 steps:

1. Learn how to construct data structures in C and pass them to perl
2. Learn to make sense and manipulate variables passed from perl in C - essentially the reverse of 1
3. Understand the various macros and perl api calls that will allow me to write good optimized code

At the end of it I am hoping to be able to write a tutorial for others like me. I am currently at the middle of Step 1 and using perldoc: perlguts as a guide. Based on this, I have written a few baby programs and I wanted to post them here and then follow them up with questions for the wise monks here around this code. First, here is a toy program that creates a string for perl to print:

#!/usr/bin/perl

use Inline C;

use strict;
use warnings;

print mkstr() . "\n";

__END__
__C__

SV* mkstr() {
    return newSVpv("This is another string!", 0);
}
[download]

Here is a program to create an array in C and use it in perl:

#!/usr/bin/perl

use Inline C;

use strict;
use warnings;

use Data::Dumper;

my $arr = mkarr();
print ref($arr) . "\n";
print Dumper($arr) . "\n";

__END__
__C__

AV* mkarr() {
    
    int i;
    int size = 10;
    
    SV** pint = (SV **) malloc(size * sizeof(SV*));
    for(i = 0; i < size; ++i)
        pint[i] = newSViv(i);

    return av_make(size, pint);    
}
[download]

Here is one that creates a hash for perl to handle:

#!/usr/bin/perl

use Inline C;

use strict;
use warnings;

use Data::Dumper;

my $hash = mkhash();
print ref($hash) . "\n";
print Dumper($hash) . "\n";

__END__
__C__

HV* mkhash() {
    
    HV *hash = newHV();
    
    hv_store(hash, "name", 5, newSVpv("John Doe", 0), 0);
    hv_store(hash, "age", 4, newSViv(42), 0);    

    return hash;    
}
[download]

Here is a program that blesses that hash in a Class:

#!/usr/bin/perl

use Inline C;

use strict;
use warnings;

use Data::Dumper;

my $obj = mkobj();
print ref($obj) . "\n";
print Dumper($obj) . "\n";

__END__
__C__

SV* mkobj() {
    
    HV* hash = newHV();
        
    hv_store(hash, "name", 5, newSVpv("John Doe", 0), 0);
    hv_store(hash, "age", 4, newSViv(42), 0);
    SV* rv = newRV_inc((SV*) hash);
    
    return sv_bless(rv, gv_stashpv("MyClass", GV_ADD));    
}
[download]

And now for a few questions around the various baby-code above:

1. If the monks here, infinitely wiser and more experienced than me were to write something like this, what parts would they write differently (to get a better understanding, not to put it in production) and why?
2. I have merrily allocated structures without a care to deallocate the space. How does one deallocate space malloc'ed in my C sections. Will perl do it for me when the program completes or do I have to do it myself?
3. In all cases, I return pointers to data structures which, except in the case of a string turn into references of the appropriate type. In the case of a string, why do I not get a reference to a perl scalar
4. If I can directly create and pass references to hashes, arrays and objects, why do I need the functions/macros provided by the perl api such as

   SV* newRV_inc((SV*) thing);

   and others mentioned in perlguts

Would really appreciate your answers and your advice. Thank you