The relationship between MULTIPLICITY and PERL_IMPLICIT_CONTEXT

What is the relationship between the Perl API macros MULTIPLICITY and PERL_IMPLICIT_CONTEXT?

According to perlguts:

One macro controls the major Perl build flavor: MULTIPLICITY. The MULTIPLICITY build has a C structure that packages all the interpreter state. With multiplicity-enabled perls, PERL_IMPLICIT_CONTEXT is also normally defined, and enables the support for passing in a "hidden" first argument that represents all three data structures.

(by the way, which "three data structures" are referred to here?)

I have noticed that when I build perl with usethreads:

./Configure -des -Dusethreads

the macros PERL_IMPLICIT_CONTEXT and MULTIPLICITY will both be set (defined). Also, in embedvar.h there is a comment that may be relevant:

The following combinations of MULTIPLICITY and PERL_IMPLICIT_CONTEXT are supported:
1) none
2) MULTIPLICITY # supported for compatibility
3) MULTIPLICITY && PERL_IMPLICIT_CONTEXT

All other combinations of these flags are errors.

only #3 is supported directly, while #2 is a special case of #3 (supported by redefining vTHX appropriately).

So, when writing XS code is there any difference in writing #ifdef MULTIPLICITY versus writing #ifdef PERL_IMPLICIT_CONTEXT?
What is the history behind the two variables? It seems like they today could be reduced to a single. For example, what would happen if all occurences of MULTIPLICITY was replaced with PERL_IMPLICIT_CONTEXT in the perl source? What would it break?

Solution

Here is what I have found so far. Running sh Configure -des creates the header config.h. This header file will:

define USE_ITHREADS if and only if Configure was given the flag -Dusethreads, e.g.:
```
sh Configure -des -Dusethreads
```
define MULTIPLICITY if and only if Configure was given the flag -Dusemultiplicity:
```
sh Configure -des -Dusemultiplicity
```
Setting MULTIPLICITY through ccflags will not set MULTIPLICITY in config.h, e.g.:
```
sh Configure -des -Accflags="-DMULTIPLICITY"
```
Configure has no -D flag for PERL_IMPLICIT_CONTEXT, and defining it through ccflags will not define it in config.h.

The generated config.h header is #included by perl.h. Note, that the latter header is also usually included by Perl XS extension files (.xs-files). At line 59 in perl.h we have:

#ifdef USE_ITHREADS  
#  if !defined(MULTIPLICITY)
#    define MULTIPLICITY
#  endif
#endif

#ifdef PERL_GLOBAL_STRUCT_PRIVATE
#  ifndef PERL_GLOBAL_STRUCT
#    define PERL_GLOBAL_STRUCT
#  endif
#endif

#ifdef PERL_GLOBAL_STRUCT
#  ifndef MULTIPLICITY
#    define MULTIPLICITY
#  endif
#endif

#ifdef MULTIPLICITY
#  ifndef PERL_IMPLICIT_CONTEXT
#    define PERL_IMPLICIT_CONTEXT
#  endif
#endif

This means that:

if -Dusethreads is given, USE_ITHREADS, MULTIPLICITY, and PERL_IMPLICIT_CONTEXT will all be defined.
if -Dusemultiplicity is given, MULTIPLICITY and PERL_IMPLICIT_CONTEXT will be defined, whereas USE_ITHREADS will be undefined.
if none of -Dusethreads or -Dusemultiplicity is given USE_ITHREADS, MULTIPLICITY, and PERL_IMPLICIT_CONTEXT will all be undefined.
it is not possible to have MULTIPLICITY defined and PERL_IMPLICIT_CONTEXT undefined (unless one uses ccflags, but then this will only be during the perl build. XS extension modules that include perl.h will not see this)

So extension modules can usually assume that either:

MULTIPLICITY and PERL_IMPLICIT_CONTEXT are both defined, or
MULTIPLICITY and PERL_IMPLICIT_CONTEXT are both undefined.