May 18, 2003

API suckitude of the first order: Perl's magic from C code

So, I'm working on my slides for my "Writing Perl Extensions in C" class, which I'm giving at OSCON this year, and for the New York Perl Seminars group this month. (the evening of Tuesday May 20th, FWIW) Now, this isn't a big deal--I've been writing XS code for years, and it isn't that tough. Perl's API is primitive, dodgy in spots, and mostly undesigned, but it's not that big a deal, and no worse than other libraries I've had to use.

Since I really hate courseware that leaves off important details, I figured I'd better poke around in the docs a bit to refresh my memory about magic. Magic, in perl 5, is that stuff that lets you write code that intercepts read and write requests to a variable. It's used to implement tied hashes/arrays/scalars, lvalues returned from substr or vec, the %ENV hash, and a few other things.


This stuff is an absolute mess. Most of the API actively ignores magic, though not all of it. The docs for parts of the API says that it does handle magic is actually incorrect. And nowhere is it particularly well emphasized that you really do need to pay attention to magic. It's... well, it's bloody annoying is what it is. To write proper code you actually need to scatter a lot of SvGETMAGIC and SvSETMAGIC calls thoughout it, to make sure that magic, if it exists on something, is properly triggered. Except when you don't, because they happen implicitly. And in those cases where you know no magic is involved.

It doesn't help that the docs are horribly scarce here, and not even the one mostly definitive work on the subject (Extending and Embedding Perl by Jenness and Cozens) doesn't touch on magic at all. I'm currently not sure what the right thing is, nor how many modules on CPAN get it right through sheer happenstance or good choice of defaults by perl. That makes me... nervous.

It's enough to tempt you to add little "This is somewhat more complex with magic" footnotes all around. Or rewrite it entirely. And since I'm doing the latter, I might do the former too. Unfortunately there's no time to do the proper research for the first runthrough, and possibly not in time for the materials turnin for OSCON, so there may well be good reason to take notes in class...

Posted by Dan at May 18, 2003 04:11 PM | TrackBack (0)

And, for extra points, the magic that the docs recommend you use, '~' magic isn't much use because it can get implicitly clobbered in strange ways. When we needed a way of doing 'out of band' storage on arbitrary objects in Pixie we ended up having to grab an unused magic specifier and hope that nobody else started using it. Thankfully it's the kind of magic that doesn't have any triggers, just a magical place to store data.

Posted by: Piers Cawley at May 19, 2003 09:37 AM