This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
support USE_THREADS+MULTIPLICITY; source compat tweaks for
[perl5.git] / pod / perlguts.pod
index 74b5ff9..4081570 100644 (file)
@@ -1522,27 +1522,28 @@ a C structure, or inside a thread.  The thread, the C structure, or
 the C++ object will contain all the context, the state of that
 interpreter.
 
-Four macros control the way Perl is built: PERL_IMPLICIT_CONTEXT
-(build for multiple interpreters?), MULTIPLICITY (we pass around an
-C interpreter structure as the first argument), USE_THREADS (we pass
-around a thread as the first argument), and PERL_OBJECT (we build a
-C++ class for the interpreter so the Perl API implementation has a
-C<this> object).  If PERL_IMPLICIT_CONTEXT is not defined, then
-subroutines take no first argument.
-
-This obviously requires a way for the Perl internal functions to be
+Three macros control the major Perl build flavors: MULTIPLICITY,
+USE_THREADS and PERL_OBJECT.  The MULTIPLICITY build has a C structure
+that packages all the interpreter state, there is a similar thread-specific
+data structure under USE_THREADS, and the PERL_OBJECT build has a C++
+class to maintain interpreter state.  In all three cases,
+PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
+support for passing in a "hidden" first argument that represents all three
+data structures.  (The traditional MULTIPLICITY and USE_THREADS builds
+built without PERL_IMPLICIT_CONTEXT may also be supported, but this is
+currently somewhat broken.)
+
+All this obviously requires a way for the Perl internal functions to be
 C++ methods, subroutines taking some kind of structure as the first
 argument, or subroutines taking nothing as the first argument.  To
 enable these three very different ways of building the interpreter,
 the Perl source (as it does in so many other situations) makes heavy
 use of macros and subroutine naming conventions.
 
-First problem: deciding which functions will be C++ public methods and
+First problem: deciding which functions will be public API functions and
 which will be private.  Those functions whose names begin C<Perl_> are
-public, and those whose names begin C<S_> are protected (think "S" for
-"Secret").  You can't call them from C++, and should not call them
-from C.  If you find yourself calling an C<S_> function, consider your
-code broken (even though it works, it may not do so forever).
+public, and those whose names begin C<S_> are private (think "S" for
+"secret" or "static").
 
 Some functions have no prefix (e.g., restore_rsfp in toke.c).  These
 are not parts of the object or pseudo-structure because you need to
@@ -1575,11 +1576,11 @@ argument containing the interpreter's context.  The trailing underscore
 in the pTHX_ macro indicates that the macro expansion needs a comma
 after the context argument because other arguments follow it.  If
 PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
-subroutine is not prototyped to take an argument.  The form of the
-macro without the trailing underscore is used when there are no
+subroutine is not prototyped to take the extra argument.  The form of the
+macro without the trailing underscore is used when there are no additional
 explicit arguments.
 
-When an core function calls another, it must pass the context.  This
+When a core function calls another, it must pass the context.  This
 is normally hidden via macros.  Consider C<sv_setsv>.  It expands
 something like this:
 
@@ -1646,11 +1647,12 @@ Thus, something like:
 
         sv_setsv(asv, bsv);
 
-in your extesion will translate to this:
+in your extesion will translate to this when PERL_IMPLICIT_CONTEXT is
+in effect:
 
         Perl_sv_setsv(GetPerlInterpreter(), asv, bsv);
 
-when PERL_IMPLICIT_CONTEXT is in effect, or to this otherwise:
+or to this otherwise:
 
         Perl_sv_setsv(asv, bsv);
 
@@ -1669,7 +1671,7 @@ your Foo.xs:
         static my_private_function(int arg1, int arg2);
 
        static SV *
-       my_private_function(pTHX_ int arg1, int arg2)
+       my_private_function(int arg1, int arg2)
        {
            dTHX;       /* fetch context */
            ... call many Perl API functions ...