https://github.com/vickenty/eu-wwg

ExtUtils::WeakWrapperGenerator
https://github.com/vickenty/eu-wwg

Last synced: 18 days ago
JSON representation

ExtUtils::WeakWrapperGenerator

• Host: GitHub
• URL: https://github.com/vickenty/eu-wwg
• Owner: vickenty
• License: bsd-3-clause
• Created: 2015-09-25T16:54:37.000Z (about 9 years ago)
• Default Branch: master
• Last Pushed: 2015-10-01T20:58:26.000Z (about 9 years ago)
• Last Synced: 2024-10-13T17:25:53.479Z (24 days ago)
• Language: Perl
• Size: 129 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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.