From Corehackers

Page Is Unavailable Due To Site Maintenance, Please Visit Reserve Copy Page

<pre>

=pod

=head1 NAME

API glossary - A glossary of XS and perl core macros

=head1 DESCRIPTION

=head2 Recurring patterns

=over 2

=item ...CXT...

It's likely about thread context and relates to a set of macros for making static/class data in XS modules thread-safe. (see L<"perlxs/Safely Storing Static Data in XS">)

=item CXt_...

Macros, constant. Type of perl context (?). Used to describe block we're entering (loop, sub, eval...). Defined in F<cop.h>. Examples: C<CXt_SUB>, C<CXt_EVAL>, C<CXt_GIVEN> (5.10).

=item d...

The C<d> indicates a macro that declares stuff. Examples: C<dTARG>, C<dTARGET>.

=item PL_...

Global variables.

=item S_...

Quoting L<perlguts>: All functions whose names begin "S_" are private (think "S" for "secret" or "static"). All other functions begin with "Perl_", but just because a function begins with "Perl_" does not mean it is part of the API. (see L<"perlguts/Internal Functions">)

=item ...THX

A macro that hides the details of the interpreter's context. THX stands for "thread", "this", or "thingy". The ellipsis could be I<p> for I<p>rototype, I<a> for I<a>rgument, or I<d> for I<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and their variants.

A trailing underscore is used if there are additional arguments. That means you would start the parameter list of a function definition with a C<pTHX> or C<pTHX_> if there are additional parameters. You would start the argument list when calling the function with C<aTHX> (or C<aTHX_>). This automatically takes care of passing the interpreter context in a C<MULTIPLICITY> enabled perl. I<dTHX> is used in context-free functions (see perlguts).

(see L<"perlguts/How multiple interpreters and concurrency are supported">)

=item XSRETURN_...

Used to return stuff from XSUBs. (Doh!) Examples: C<XSRETURN_EMPTY> (empty list), C<XSRETURN_UNDEF>, etc. (see: L<perlapi>)

=back

=head2 Misc. Glossary

Note: This is just some stuff that irked me while learning XS. It is extremely incomplete and risks duplicating much of perlapi. Maybe some of these should be amended in perlapi and other places, but probably, they should simply be discarded.

=over 2

=item dVAR

Declares the interpreter-global variables for use in the function. Part of C<dTHX>. (see L<"perlguts/How multiple interpreters and concurrency are supported">, L</d...> pattern)

=item ENTER

B<API>. Think of it like the start of a temporary scope. Similar to "{" in Perl. (see L<perlapi/ENTER>, L<perlhack/Stacks>, L<perlcall>, L</LEAVE>)

=item LEAVE

B<API>. Think of it like the end of a temporary scope. Similar to "}" in Perl. (see L<perlhack/Stacks>, L<perlcall>, L</ENTER>)

=back

=head1 AUTHOR

Originally written by Steffen Mueller <smueller@cpan.org> and... you!

=cut

</pre>