Chapter 9

The moral of this story is that managing memory usage in C modules is rarely 

simple. It requires you to think carefully about the way the underlying library allo 

cates memory. Often the only way to get some of the information you need is to 

test. For example, the only way I could find out that gnome_mime_type() doesn't 

dynamically allocate its return value was to run my wrapped version in a loop and 

watch the system with top in another window:

$ perl  Mblib  MGnome::MIME  e  while(1) { Gnome::MIME::file_type("foo.gif"); } 

It's a good idea to do this sort of testing on all your XS functions at least until 

someone finds a way to write ExtUtils::LeakDetector!

XS Interface Design and Construction

Being able to easily produce one to one mappings between a set of C functions 

and subroutines in a Perl module is undeniably very useful. XS is designed to allow 

you to accomplish this task with a minimum amount of coding required; simply 

describe the C functions, and out pops a new module, fully baked and ready to 

consume. Unfortunately, much like a microwave dinner, the ease of preparation 

comes at a price in palatability.

Consider the interface that Gnome::MIME would provide if this recipe were 

followed for each function in the API. The Gnome MIME type functions follow a 

common pattern in C APIs they provide a variety of functions that all perform 

the same task with different parameters:

$type = Gnome::MIME::type($filename);

$type = Gnome::MIME::type_or_default($filename, $default);

$type = Gnome::MIME::type_of_file($filename);

$type = Gnome::MIME::type_or_default_of_file($filename, $default);

The or_default versions allow the user to specify a default to be returned if the 

MIME type cannot be determined. The of_file versions actually read from the file 

to guess its MIME type rather than relying on the filename alone. However, every 

one of these functions provides the same core functionality determining the 

MIME type of a file. Clearly this would be a difficult module for a Perl programmer 

to use if he or she had to pick from the preceding function list. To make matters 

worse, module authors who allow XS to write their interfaces often abdicate on the 

documentation as well, saying something along the lines of  I've wrapped every C 

function in the library, see the docs for the C library for details. 

Every module needs to have a sensible interface. Whether it's implemented in 

Perl or in C shouldn't determine the interface used. This section will give you some 

ideas about how to design and code better XS interfaces.

220