I'm pretty fuzzy about these things too, so I'll write up a response to make myself figure it out.

First, the READONLY flag is set on the SV containing the pointer value (as an IV). This is for safety. Without this, you could do $$obj1++ and get a segmentation fault the next time you called any Inline method on the object. (It should really be a bus error, but I get a seg fault. Hmf.) Modifying pointer values from Perl is rarely useful and usually disastrous, so it's nice to lock them down to prevent accidental corruption.

Second, you can have the equivalent effect as the Cookbook example with:

   obj_ref = sv_setref_pv(newSViv(0), class, (void *)soldier);
   SvREADONLY_on(SvRV(obj_ref));
   return obj_ref;
[download]

Now, as for exactly what's going on, I'm much shakier. I have long used the Cookbook code exactly as-is because it's never made sense to me. I now suspect that it has nothing to do with me; it really doesn't make sense.

In particular, notice how obj_ref is initialized with newSViv. I think the "iv" part of that is irrelevant; the IV part of obj_ref has nothing to do with the IV that ends up holding the Soldier pointer. In fact, you can replace newSViv with newSVnv -- or even newSV, which would make the most sense. You will get a different result when you dump the variable -- instead of obj_ref dumping to a PVIV that happens to have its RV field (and ROK flag) set, you will get a plain RV. But that seems, to my eye, in all ways better. I would go so far as to say that the Cookbook code is buggy -- it is wasteful of memory and highly confusing to boot.

So if you use newRV, it all seems to make sense: obj_ref is an RV that points to a blessed SV holding an IV, and that IV is the pointer value. The blessed SV should naturally be READONLY because you don't want anyone mucking with the pointer value.

For the time being, I will ignore my own confusion as to why the IV-containing SV is blessed into a package, rather than the RV.

With this understanding, I think the following code should have the equivalent effect:

  SV* obj = newSViv((IV)soldier);
  SV* obj_ref = newRV_noinc(obj);
  sv_bless(obj_ref, gv_stashpv(class, TRUE));
  SvREADONLY_on(obj);
  return obj_ref;
[download]

which is far easier to understand, though much less slick than Ken's. Especially when you get rid of the bogus newSViv, and just use:

   obj_ref = sv_setref_pv(newSV(0), class, (void *)soldier);
   SvREADONLY_on(SvRV(obj_ref));
   return obj_ref;
[download]

Wow. I think I finally understand what's going on now. Thank you for asking the question!

Well, everything but why blessing modifies referenced SV's instead of the referencing SV's. Anyone?

Oh, and one last thing -- I handle the typemap file by relying on the fact that I'm compiling with gcc, and can use its ({ ... }) construct. Here's an excerpt from my typemap:

GrNode *                T_GR_NODE

INPUT
T_GR_NODE
        $var = (GrNode*) ({ SV* arg = $arg; SV* tmp = arg && SvROK(arg
+) ? SvRV(arg) : 0; tmp && SvIOK(tmp) ? SvIV(tmp) : 0; });

OUTPUT
T_GR_NODE
        $arg = $var ? wrap("Rx::DOM::Node", $var) : &PL_sv_undef;
[download]

I'm not sure why I use an external function in the OUTPUT map but do it all messily inline in the INPUT map. Obviously, you could put all the code you need into the OUTPUT too.