yet it's not what I naively expected.

I have similar reservations about the Object Oriented Inline example in the cookbook:

SV* new(char* class, char* name, char* rank, long serial) {
    Soldier* soldier;
    SV*      obj_ref = newSViv(0);
    SV*      obj = newSVrv(obj_ref, class);
    
    New(42, soldier, 1, Soldier);
    soldier->name = savepv(name);
    soldier->rank = savepv(rank);
    soldier->serial = serial;
        
    sv_setiv(obj, (IV)soldier);
    SvREADONLY_on(obj);
    return obj_ref;
}
[download]

obj_ref is an IV (set to 0), pointed at by obj which is an RV, who's IV is set to the address of the struct and then set read only. But then it is obj_ref that is returned.

• Why is the RV called obj and the thing it points to call obj_ref?
• Why is obj_ref returned when it is an IV that has only ever been set to 0?
• How can we (now, since 5.14?), assign the address of the struct to the IV component of obj (which is constructed as an RV remember) without overwriting the pointer now that they are one and the same piece of memory?

Then again, I find almost nothing about XS intuitive and the documentation is shite. If you ask questions about it you either get no answers or an answer of "Do this", with no explanation of why that works. And that smacks of the passing on of rote learnt knowledge with no true understanding. If there is anyone left who really understands this stuff, they are keeping that knowledge firmly to themselves.

If I could get help in understanding this stuff I might have published a whole lot more of my half-finished, but dead-in-the-water projects.