sv.h - add SvREFCNT_dec_set_NULL()

and also SvREFCNT_dec_ret_NULL() which is used to implement
SvREFCNT_dec_set_NULL(). The set_NULL() macro is intended to
be used to replace code like this:

    if (sv) {
        SvREFCNT_dec_NN(sv);
        sv = NULL;
    }

The function form just facilitates it, and can be used in situations
where returning NULL after decrementing a refcount would be reduce
code complexity.

Author: demerphq

embed.fnc

@@ -3202,6 +3202,10 @@ Adp	|SV *	|sv_ref 	|NULLOK SV *dst 			\
 				|const int ob
 AMdip	|void	|SvREFCNT_dec	|NULLOK SV *sv
 AMdip	|void	|SvREFCNT_dec_NN|NN SV *sv
+Adip	|SV *	|SvREFCNT_dec_ret_NULL					\
+				|NULLOK SV *sv
+Adm	|void	|SvREFCNT_dec_set_NULL					\
+				|NULLOK SV *sv
 AMTdip	|SV *	|SvREFCNT_inc	|NULLOK SV *sv
 AMTdip	|SV *	|SvREFCNT_inc_NN|NN SV *sv
 AMTdip	|void	|SvREFCNT_inc_void					\

embed.h

@@ -107,6 +107,7 @@
 # define SvNV(a)                                Perl_SvNV(aTHX_ a)
 # define SvNV_nomg(a)                           Perl_SvNV_nomg(aTHX_ a)
 # define SvPVXtrue(a)                           Perl_SvPVXtrue(aTHX_ a)
+# define SvREFCNT_dec_ret_NULL(a)               Perl_SvREFCNT_dec_ret_NULL(aTHX_ a)
 # define SvTRUE(a)                              Perl_SvTRUE(aTHX_ a)
 # define SvTRUE_NN(a)                           Perl_SvTRUE_NN(aTHX_ a)
 # define SvTRUE_common(a,b)                     Perl_SvTRUE_common(aTHX_ a,b)

proto.h

@@ -336,13 +336,30 @@ effects and you don't need the return value.
 C<SvREFCNT_inc_simple_void_NN> can only be used with expressions without side
 effects, you don't need the return value, and you know C<sv> is not C<NULL>.
 
-=for apidoc SvREFCNT_dec
-=for apidoc_item SvREFCNT_dec_NN
+=for apidoc            SvREFCNT_dec
+=for apidoc_item       SvREFCNT_dec_set_NULL
+=for apidoc_item |SV*|SvREFCNT_dec_ret_NULL|SV *sv
+=for apidoc_item       SvREFCNT_dec_NN
 
 These decrement the reference count of the given SV.
 
 C<SvREFCNT_dec_NN> may only be used when C<sv> is known to not be C<NULL>.
 
+The function C<SvREFCNT_dec_ret_NULL()> is identical to the
+C<SvREFCNT_dec()> except it returns a NULL C<SV *>.  It is used by
+C<SvREFCNT_dec_set_NULL()> which is a macro which will, when passed a
+non-NULL argument, decrement the reference count of its argument and
+then set it to NULL. You can replace code of the following form:
+
+    if (sv) {
+       SvREFCNT_dec_NN(sv);
+       sv = NULL;
+    }
+
+with
+
+    SvREFCNT_dec_set_NULL(sv);
+
 =for apidoc Am|svtype|SvTYPE|SV* sv
 Returns the type of the SV.  See C<L</svtype>>.
 
@@ -375,6 +392,10 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 #define SvREFCNT_inc_simple_void_NN(sv)	(void)(++SvREFCNT(MUTABLE_SV(sv)))
 
 #define SvREFCNT_dec(sv)	Perl_SvREFCNT_dec(aTHX_ MUTABLE_SV(sv))
+#define SvREFCNT_dec_set_NULL(sv)                               \
+    STMT_START {                                                \
+        sv = Perl_SvREFCNT_dec_ret_NULL(aTHX_ MUTABLE_SV(sv));  \
+    } STMT_END
 #define SvREFCNT_dec_NN(sv)	Perl_SvREFCNT_dec_NN(aTHX_ MUTABLE_SV(sv))
 
 #define SVTYPEMASK	0xff

sv.h

@@ -664,6 +664,7 @@ Perl_SvREFCNT_inc(SV *sv)
         SvREFCNT(sv)++;
     return sv;
 }
+
 PERL_STATIC_INLINE SV *
 Perl_SvREFCNT_inc_NN(SV *sv)
 {
@@ -672,12 +673,14 @@ Perl_SvREFCNT_inc_NN(SV *sv)
     SvREFCNT(sv)++;
     return sv;
 }
+
 PERL_STATIC_INLINE void
 Perl_SvREFCNT_inc_void(SV *sv)
 {
     if (LIKELY(sv != NULL))
         SvREFCNT(sv)++;
 }
+
 PERL_STATIC_INLINE void
 Perl_SvREFCNT_dec(pTHX_ SV *sv)
 {
@@ -690,6 +693,15 @@ Perl_SvREFCNT_dec(pTHX_ SV *sv)
     }
 }
 
+PERL_STATIC_INLINE SV *
+Perl_SvREFCNT_dec_ret_NULL(pTHX_ SV *sv)
+{
+    PERL_ARGS_ASSERT_SVREFCNT_DEC_RET_NULL;
+    Perl_SvREFCNT_dec(aTHX_ sv);
+    return NULL;
+}
+
+
 PERL_STATIC_INLINE void
 Perl_SvREFCNT_dec_NN(pTHX_ SV *sv)
 {