these macros can be found in Inline/C.pm

The problem is not in finding their definitions, it is understanding what they do, when they must be used and when not etc.

Their definitions are all in terms of other (XS) macros, and unwinding those is much harder. And once you have unwound them to the actual code that gets executed, it is generally a horrible mess of nested macro expansions calling a bunch of undocumented apis -- often repetitively -- and manipulating another bunch of undocumented global variables.

Trying to work out what calls are actually need when, rather than just cargo-culting someone else who cargo-culted someone else who ... is very difficult. Weirdness like the completely unused & redundant PUTBACK; return; sequence generated by the Inline::C wrapper functions just compounds matters.

I think these macros are mostly useful for beginners in that they provide a mantra that gets most jobs done - and despite their verbosity, are easier to remember than the corresponding list of XS symbols.

Do you really find verbosity more memorable than conciseness? I don't. I realise that you inherited those definitions, but I think that it is a fallacy to believe they are more memorable than the XS_equivalents.

With Ike's help above, I've reduced my fast random generator to:

void rnd64( int n ) {
    dXSARGS;
    static unsigned __int64 y = 88172645463325252i64;

    EXTEND( SP, n );
    while( n-- ) {
        y ^= y << 13;
        y ^= y >> 7;
        y ^= y << 17;
        mPUSHu( y );
    }
    PUTBACK;
    return;
}
[download]

Which appears to work well. It doesn't appear to leak any memory after producing over 12 billion 64-bit rands (in batches of 1 million) in an hour , but that still leaves me with the question of whether I should be resetting the stack to account for the single input parameter, or whether the EXTEND() takes care for that for me?

And it is this aspect of using Inline::C or XS that leaves me cold. The reason for dipping into the quagmire is to achieve speed unobtainable in Perl, but working out what bits of the templated examples are actually required and when is (it seems) only possible by suck-it-and-see.

I also wonder if I shouldn't be passing in a reference to the an array and populating it directly, rather than assigning the returned stack to it?

Equally, rather than creating a whole new bunch of SVs to hold my rands in the target array, couldn't I just modify their IVs in place? Would that be more efficient?