Structuring Ruby extension code

[craig duncan]

I'm relatively new to Ruby (in terms of seriously programming in it) and right now i
want to create a C extension for the low-level ogg/vorbis libraries. I have the
basic architecture for this mapped out in my head and i'm able to look at the
wrapping that someone has already done for the higher-level libvorbisfile library.
At the very beginning of that extension's Init_vorbisfile function it does:

cOgg = rb_define_module("Ogg");
cVorbisFile = rb_define_class_under(cOgg, "VorbisFile", rb_cObject);
rb_define_singleton_method(cVorbisFile, "new", vf_s_new, -1);

Looking at this has me a little confused because that's now what i had in mind to do.
I had no thought of creating a module, and i thought i would just create the
OggStream class i want to define directly with:

cLibOgg = rb_define_class("OggStream", rb_cObject);

I also hadn't identified any need to define "new" as a singleton method. So... Can
anybody provide me with an at least plausible rationale for what advantages there
might be in defining a module in this situation, and then for using
define_class_under to define the class... and for creating this one singleton method
(all the other methods defined after this just use rb_define_method). Maybe the
vf_s_new function is something that's only supposed to be called once. But, limited
as my understanding of Ruby is, i don't understand exactly the connection between
that and defining "new" as a singleton method. What exactly does making something a
singleton method preclude (trying to answer my own questions)? The obvious answer
is: creating more than one instance. But when that applies to a method... i don't
get it (this singleton stuff has never been completely clear to me in all its nuances).

Groping for an answer some more... does creating an "Ogg" module this way allow
someone else (like me, in this instance) to also define the _same_ module in my
extension and if both extensions are loaded at the same time they go into the same
module namespace and there's some benefit in this?

Any insights into any or all of this will be greatly appreciated.

craig

 

[Timothy Hunter]

I'm relatively new to Ruby (in terms of seriously programming in it)
and right now i want to create a C extension for the low-level
ogg/vorbis libraries. I have the basic architecture for this mapped
out in my head and i'm able to look at the wrapping that someone has
already done for the higher-level libvorbisfile library.
At the very beginning of that extension's Init_vorbisfile function it does:

cOgg = rb_define_module("Ogg");
cVorbisFile = rb_define_class_under(cOgg, "VorbisFile", rb_cObject);
rb_define_singleton_method(cVorbisFile, "new", vf_s_new, -1);

Looking at this has me a little confused because that's now what i had
in mind to do. I had no thought of creating a module, and i
thought i would just create the OggStream class i want to define
directly with:

cLibOgg = rb_define_class("OggStream", rb_cObject);

I also hadn't identified any need to define "new" as a singleton
method. So... Can anybody provide me with an at least plausible
rationale for what advantages there might be in defining a module in
this situation, and then for using define_class_under to define the
class... and for creating this one singleton method (all the other
methods defined after this just use rb_define_method). Maybe the
vf_s_new function is something that's only supposed to be called once.
But, limited as my understanding of Ruby is, i don't understand exactly
the connection between that and defining "new" as a singleton method.
What exactly does making something a singleton method preclude (trying
to answer my own questions)? The obvious answer is: creating more than
one instance. But when that applies to a method... i don't get it
(this singleton stuff has never been completely clear to me in all its
nuances).

Groping for an answer some more... does creating an "Ogg" module this
way allow someone else (like me, in this instance) to also define the
_same_ module in my extension and if both extensions are loaded at the
same time they go into the same module namespace and there's some
benefit in this?

Any insights into any or all of this will be greatly appreciated.

craig

The module is there to prevent namespace pollution. By defining the Ogg
module you are reserving the Ogg namespace instead of inserting your
classes into the top-level namespace. It's a courtesy to your users.

Defining a singleton method called `new' is the old way to define the
`new' class method. In 1.8.0 and later, use the rb_define_alloc_func
function. See the PickaxeII for more information.

 

[craig duncan]

On 2005-02-13 02:37:33 -0500, craig duncan <[email protected]>
said:


The module is there to prevent namespace pollution. By defining the Ogg
module you are reserving the Ogg namespace instead of inserting your
classes into the top-level namespace. It's a courtesy to your users.

Thanks. I kind of understood this. If there was no C extension involved, the
question wouldn't even have occurred to me. But trying to get my brain around how
the extension stuff works is fuzzing my brain. There isn't enough of a basic
explanation of the fundamentals anywhere, as far as i can tell (except the pickaxe book).

Defining a singleton method called `new' is the old way to define the
`new' class method. In 1.8.0 and later, use the rb_define_alloc_func
function. See the PickaxeII for more information.

Thanks for the info. It's a shame the documentation situation is the way that it is.
In order to get _any_ documentation for the version i'm running (and coding to),
i've got to go buy a (very good, admittedly) book. I already bought the first
pickaxe book. Can't i get an upgrade.

 

[why the lucky stiff]

Thanks for the info. It's a shame the documentation situation is the
way that it is. In order to get _any_ documentation for the version
i'm running (and coding to), i've got to go buy a (very good,
admittedly) book. I already bought the first pickaxe book. Can't i
get an upgrade.

Sure. Send me your copy and I will manually inscribe the updates in
black india ink.

Incidentally, there's a knock knock joke in the Ruby world that goes
something like this.

Knock Knock
Who's there?
Ruby.
Ruby who?
Ruby <EUC-JP encoded answer.>

At least there's not an overage of bad information. And really, it is
nice that PickAxeII is all you need to master Ruby itself.

_why

 

[craig duncan]

Sure. Send me your copy and I will manually inscribe the updates in
black india ink.

That would be a lot of work, though, wouldn't it? I think it'd make more sense for
me to buy the online version, send you my copy, and have you inscribe foxes on it.

Incidentally, there's a knock knock joke in the Ruby world that goes
something like this.

Knock Knock
Who's there?
Ruby.
Ruby who?
Ruby <EUC-JP encoded answer.>

Wish i got it.

At least there's not an overage of bad information. And really, it is
nice that PickAxeII is all you need to master Ruby itself.

_why

Yes. It's an excellent book (hoping the 2nd edition is just as good... no: better
... than the first). But on the other hand, just think about this: Many features of
1.8 (including writing C extensions) are inadequately (or less) documented outside of
the pickaxe book.

It's wonderful that the book is there. But what other open-source project is in the
situation where the only reasonably good and complete documentation is only available
by purchasing it. This is an obstacle that i hope Ruby surmounts in the not too
distant future... although i don't know how it will happen.

craig

 

[Brian Schröder]

Wish i got it.

I think this is making fun with the fact, that you often only see japanese characters when searching for a ruby application. And if you'r lucky you get a altavista translated english version of the site to help you have a funny day laughing about automatic translation programs.

Regards,

Brian