/eu-wwg

ExtUtils::WeakWrapperGenerator

Primary LanguagePerlBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

NAME

ExtUtils::WeakWrapperGenerator - generate OO wrappers for OO-ish C libraries

DESCRIPTION

Some C libraries are written in a nicely structured OO-like way. Others try to simplify developer's life by managing memory in chunks using scope or context objects. The former usually true for large libraries, and the latter makes bindings to garbage collected languages slightly less straightforward. Two things combined prove to be more work than its worth.

This package can semi-automatically build OO-style wrappers for XS bindings to C libraries that have both OO-like design and context-style memory management.

Assumptions

Library functions are named in a way that clearly indicates which class it belongs and which method it implements. The first argument of the function is pointer to self.

 void dancer_dance(dancer_t dancer, dance_t dance); // GOOD
 void tango(int times, dancer_t dancer); // Not so much

Library manages memory for the programmer, and lends pointers out. Lent pointers become invalid when memory managing object is destroyed (via a library call).

 dancer_t* party_new_dancer(party_t party, const char* name);
 party_over(party_t party); // frees all dancers created via party_new_dancer().

It makes sense if borrowed objects become invalid once their owner is destroyed.

 my $dancer = $party->new_dancer("Alice");
 $party = undef;
 $dancer->dance(); # dies "party is over"

User is not averse to the idea of exposing types generated by xsubpp to the user.

Given a snippet from the original XS file (functions and return types) for every XS function we do:

  • determine class and method name from the function name
  • resolve class name into corresponding Perl package name
  • call hooks to initialize packages for the class and return value
  • if return type package has method WRAP, it will be called on the value returned by XS function with current object as an argument
  • if class package implements BEFORE it will be called before calling XS function

A helper is provided to generate packages that implement WRAP and BEFORE and utilize weak references to keep track of object's owner and die when it goes away.