die() now is die_nocontext; combine perlapi croak/die forms

autodoc.pl

@@ -87,7 +87,6 @@
 # This is a copy of the list in regen/embed.pl.
 my @have_compatibility_macros = qw(
                                     deb
-                                    die
                                     form
                                     load_module
                                     mess

embed.fnc

@@ -1029,7 +1029,7 @@ ETXdp	|char * |delimcpy_no_escape					\
 				|const int delim			\
 				|NN I32 *retlen
 Cp	|void	|despatch_signals
-Adfpr	|OP *	|die		|NULLOK const char *pat 		\
+AMdfpr	|OP *	|die		|NULLOK const char *pat 		\
 				|...
 Adpr	|OP *	|die_sv 	|NN SV *baseex
 : Used in util.c
@@ -3371,7 +3371,7 @@ Adp	|char * |sv_2pv_flags	|NN SV * const sv			\
 				|NULLOK STRLEN * const lp		\
 				|const U32 flags
 CIp	|char * |SvPV_helper	|NN SV * const sv				\
-				|NN STRLEN * const lp				\
+				|NULLOK STRLEN * const lp			\
 				|const U32 flags				\
 				|const PL_SvPVtype type 			\
 				|NN Perl_SvPV_helper_non_trivial_t  non_trivial \
@@ -4541,7 +4541,7 @@ S	|bool	|parse_gv_stash_name					\
 				|const U32 is_utf8			\
 				|const I32 add
 S	|void	|require_tie_mod|NN GV *gv				\
-				|NN const char varname			\
+				|const char varname			\
 				|NN const char *name			\
 				|STRLEN len				\
 				|const U32 flags
@@ -5555,8 +5555,8 @@ ES	|SV *	|reg_scan_name	|NN RExC_state_t *pRExC_state		\
 ETi	|char * |reg_skipcomment|NN RExC_state_t *pRExC_state		\
 				|NN char *p
 ERS	|bool	|regtail	|NN RExC_state_t *pRExC_state		\
-				|NN const regnode_offset p		\
-				|NN const regnode_offset val		\
+				|const regnode_offset p 		\
+				|const regnode_offset val		\
 				|const U32 depth
 ES	|void	|set_regex_pv	|NN RExC_state_t *pRExC_state		\
 				|NN REGEXP *Rx

embed.h

@@ -30,7 +30,6 @@
 #if !defined(MULTIPLICITY)
 /* undefined symbols, point them back at the usual ones */
 # define Perl_deb_nocontext                     Perl_deb
-# define Perl_die_nocontext                     Perl_die
 # define Perl_form_nocontext                    Perl_form
 # define Perl_load_module_nocontext             Perl_load_module
 # define Perl_mess_nocontext                    Perl_mess
@@ -78,7 +77,6 @@
 #   if  defined(MULTIPLICITY) && !defined(PERL_NO_SHORT_NAMES) && \
        !defined(PERL_WANT_VARARGS)
 #     define deb                                Perl_deb_nocontext
-#     define die                                Perl_die_nocontext
 #     define form                               Perl_form_nocontext
 #     define load_module                        Perl_load_module_nocontext
 #     define mess                               Perl_mess_nocontext
@@ -913,7 +911,6 @@
 # if !defined(MULTIPLICITY) || defined(PERL_CORE) || \
       defined(PERL_WANT_VARARGS)
 #   define deb(...)                             Perl_deb(aTHX_ __VA_ARGS__)
-#   define die(...)                             Perl_die(aTHX_ __VA_ARGS__)
 #   define form(...)                            Perl_form(aTHX_ __VA_ARGS__)
 #   define load_module(a,b,...)                 Perl_load_module(aTHX_ a,b,__VA_ARGS__)
 #   define mess(...)                            Perl_mess(aTHX_ __VA_ARGS__)

regen/embed.pl

@@ -42,7 +42,6 @@ BEGIN
 # to never happen, so not worth coding automatic synchronization.
 my @have_compatibility_macros = qw(
                                     deb
-                                    die
                                     form
                                     load_module
                                     mess

util.c

@@ -1757,16 +1757,6 @@ Perl_invoke_exception_hook(pTHX_ SV *ex, bool warn)
     return FALSE;
 }
 
-/*
-=for apidoc die_sv
-
-This behaves the same as L</croak_sv>, except for the return type.
-It should be used only where the C<OP *> return type is required.
-The function never actually returns.
-
-=cut
-*/
-
 /* silence __declspec(noreturn) warnings */
 MSVC_DIAG_IGNORE(4646 4645)
 OP *
@@ -1779,21 +1769,6 @@ Perl_die_sv(pTHX_ SV *baseex)
 }
 MSVC_DIAG_RESTORE
 
-/*
-=for apidoc      die
-=for apidoc_item die_nocontext
-
-These behave the same as L</croak>, except for the return type.
-They should be used only where the C<OP *> return type is required.
-They never actually return.
-
-The two forms differ only in that C<die_nocontext> does not take a thread
-context (C<aTHX>) parameter, so is used in situations where the caller doesn't
-already have the thread context.
-
-=cut
-*/
-
 #if defined(MULTIPLICITY)
 
 /* silence __declspec(noreturn) warnings */
@@ -1827,27 +1802,6 @@ Perl_die(pTHX_ const char* pat, ...)
 }
 MSVC_DIAG_RESTORE
 
-/*
-=for apidoc croak_sv
-
-This is an XS interface to Perl's C<die> function.
-
-C<baseex> is the error message or object.  If it is a reference, it
-will be used as-is.  Otherwise it is used as a string, and if it does
-not end with a newline then it will be extended with some indication of
-the current location in the code, as described for L</mess_sv>.
-
-The error message or object will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler.  In any case, the C<croak_sv>
-function never returns normally.
-
-To die with a simple string message, the L</croak> function may be
-more convenient.
-
-=cut
-*/
-
 void
 Perl_croak_sv(pTHX_ SV *baseex)
 {
@@ -1857,31 +1811,6 @@ Perl_croak_sv(pTHX_ SV *baseex)
     die_unwind(ex);
 }
 
-/*
-=for apidoc vcroak
-
-This is an XS interface to Perl's C<die> function.
-
-C<pat> and C<args> are a sprintf-style format pattern and encapsulated
-argument list.  These are used to generate a string message.  If the
-message does not end with a newline, then it will be extended with
-some indication of the current location in the code, as described for
-L</mess_sv>.
-
-The error message will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler.  In any case, the C<croak>
-function never returns normally.
-
-For historical reasons, if C<pat> is null then the contents of C<ERRSV>
-(C<$@>) will be used as an error message or object instead of building an
-error message from arguments.  If you want to throw a non-string object,
-or build an error message in an SV yourself, it is preferable to use
-the L</croak_sv> function, which does not involve clobbering C<ERRSV>.
-
-=cut
-*/
-
 void
 Perl_vcroak(pTHX_ const char* pat, va_list *args)
 {
@@ -1891,30 +1820,50 @@ Perl_vcroak(pTHX_ const char* pat, va_list *args)
 }
 
 /*
-=for apidoc croak
+=for apidoc      croak
+=for apidoc_item croak_sv
+=for apidoc_item vcroak
+=for apidoc_item die
+=for apidoc_item die_sv
 =for apidoc_item croak_nocontext
+=for apidoc_item die_nocontext
 
 These are XS interfaces to Perl's C<die> function.
 
-They take a sprintf-style format pattern and argument list, which are used to
-generate a string message.  If the message does not end with a newline, then it
-will be extended with some indication of the current location in the code, as
-described for C<L</mess_sv>>.
+The arguments are used to generate a string message.  If the message does not
+end with a newline, it will be extended with some indication of the current
+location in the code, as described for C<L</mess_sv>>.
+
+The error message will be used as an exception, by default returning control to
+the nearest enclosing C<eval>, but subject to modification by a
+C<$SIG{__DIE__}> handler.  In any case, none of these functions ever actually
+return normally.
+
+In C<croak_sv> and C<die_sv>, C<baseex> is the error message or object.  If it
+is a reference, it will be used as-is.  Otherwise it is used as a string.
+
+To die with a simple string message, one of the other forms may be more
+convenient.  These take a sprintf-style format pattern, with arguments, to
+generate the message.
+
+The arguments to C<vcroak> are specified as a C<va_list>.  The arguments to the
+remaining forms are specified as a sprintf-style list of arguments.
 
-The error message will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler.  In any case, these croak
-functions never return normally.
+In the non-C<_sv> forms, for historical reasons, if C<pat> is null then the
+contents of C<L</ERRSV>> (C<$@>) will be used as an error message or object
+instead of building an error message from arguments.  Use the C<_sv> forms
+instead if you want to throw a non-string object, or build an error message in
+an SV yourself; these do not involve clobbering C<ERRSV>.
 
-For historical reasons, if C<pat> is null then the contents of C<ERRSV>
-(C<$@>) will be used as an error message or object instead of building an
-error message from arguments.  If you want to throw a non-string object,
-or build an error message in an SV yourself, it is preferable to use
-the C<L</croak_sv>> function, which does not involve clobbering C<ERRSV>.
+The difference between the C<croak> forms and the C<die> forms is only the
+return type of the functions.  The C<croak> forms return C<void>; the C<die>
+ones are listed as returning (confusingly) an S<C<OP *>>, even though they
+never actually return.  The C<die> forms should only be used when that return
+type is required.
 
-The reasons for the existence of C<croak_nocontext> are no longer applicable.
-croak() can now be used in all circumstances.  C<Perl_croak_nocontext> might be
-useful when compiling with C<PERL_NO_SHORT_NAMES>.
+When called from outside the perl core, plain C<croak> and C<die> have always
+been the same as C<croak_nocontext> and C<die_no_context>, respectively.  That
+is now true even when called from within core.
 
 =cut
 */

util.h

@@ -11,14 +11,16 @@
 #ifndef PERL_UTIL_H_
 #define PERL_UTIL_H_
 
-/*  Calling Perl_croak_nocontext instead of plain Perl_croak is one less
- *  argument to pass under threads, so each instance takes up fewer bytes (but
- *  the nocontext function has to derive the thread context itself, taking more
- *  time).  We trade time for less space here, because time is rarely a
+/*  Calling Perl_(croak|die)_nocontext instead of plain Perl_(croak|die) is one
+ *  less argument to pass under threads, so each instance takes up fewer bytes
+ *  (but the nocontext function has to derive the thread context itself, taking
+ *  more time).  We trade time for less space here, because time is rarely a
  *  critical resource when you are about to throw an exception. */
 #define croak(...)  Perl_croak_nocontext(__VA_ARGS__)
+#define die(...)    Perl_die_nocontext(__VA_ARGS__)
 #ifndef MULTIPLICITY
 #  define Perl_croak_nocontext  Perl_croak
+#  define Perl_die_nocontext  Perl_die
 #endif
 
 #ifdef VMS