Change the first argument of Perl_fetch_cop_label() to COP *

From a suggestion from Ben Morrow.

The first argument used to be struct refcounted_he *, which exposed an
implementation detail - that the COP's labels are (now) stored in this way.

Google Code Search and an unpacked CPAN both fail to find any users of this
API, so the impact should be minimal.

6 files changed, 21 insertions, 12 deletions

diff --git a/cop.h b/cop.h
index e5370c4915..8139d4815b 100644
--- a/cop.h
+++ b/cop.h
@@ -243,7 +243,7 @@ struct cop {
 #  define CopFILE_free(c)	(SvREFCNT_dec(CopFILEGV(c)),(CopFILEGV(c) = NULL))
 
 #endif /* USE_ITHREADS */
-#define CopLABEL(c)  Perl_fetch_cop_label(aTHX_ (c)->cop_hints_hash, NULL, NULL)
+#define CopLABEL(c)  Perl_fetch_cop_label(aTHX_ (c), NULL, NULL)
 #define CopLABEL_alloc(pv)	((pv)?savepv(pv):NULL)
 
 #define CopSTASH_ne(c,hv)	(!CopSTASH_eq(c,hv))
diff --git a/embed.fnc b/embed.fnc
index ddc3173be8..63269f0f7e 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -2379,7 +2379,7 @@ p	|void   |boot_core_mro
 Apon	|void	|sys_init	|NN int* argc|NN char*** argv
 Apon	|void	|sys_init3	|NN int* argc|NN char*** argv|NN char*** env
 Apon	|void	|sys_term
-ApoM	|const char *|fetch_cop_label|NULLOK struct refcounted_he *const chain \
+ApoM	|const char *|fetch_cop_label|NN COP *const cop \
 		|NULLOK STRLEN *len|NULLOK U32 *flags
 : Only used  in op.c
 xpoM	|void|store_cop_label \
diff --git a/hv.c b/hv.c
index d8ba456745..567b4d973d 100644
--- a/hv.c
+++ b/hv.c
@@ -2940,8 +2940,11 @@ Perl_refcounted_he_free(pTHX_ struct refcounted_he *he) {
 /* pp_entereval is aware that labels are stored with a key ':' at the top of
    the linked list.  */
 const char *
-Perl_fetch_cop_label(pTHX_ struct refcounted_he *const chain, STRLEN *len,
-		     U32 *flags) {
+Perl_fetch_cop_label(pTHX_ COP *cop, STRLEN *len, U32 *flags) {
+    struct refcounted_he *const chain = cop->cop_hints_hash;
+
+    PERL_ARGS_ASSERT_FETCH_COP_LABEL;
+
     if (!chain)
 	return NULL;
 #ifdef USE_ITHREADS
diff --git a/pod/perl5135delta.pod b/pod/perl5135delta.pod
index 350f4b1232..33886605b8 100644
--- a/pod/perl5135delta.pod
+++ b/pod/perl5135delta.pod
@@ -63,12 +63,15 @@ L</Selected Bug Fixes> section.
 
 =head1 Incompatible Changes
 
-XXX For a release on a stable branch, this section aspires to be:
+=head2 C API changes
 
-    There are no changes intentionally incompatible with 5.XXX.XXX. If any
-    exist, they are bugs and reports are welcome.
+The first argument of the C API function C<Perl_fetch_cop_label> has changed
+from C<struct refcounted he *> to C<COP *>, to better insulate the user from
+implementation details.
 
-[ List each incompatible change as a =head2 entry ]
+This API function was marked as "may change", and likely isn't in use outside
+the core. (Neither an unpacked CPAN, nor Google's codesearch, finds any other
+references to it.)
 
 =head1 Deprecations
 
diff --git a/pp_ctl.c b/pp_ctl.c
index 1e90894f16..8c0c52018a 100644
--- a/pp_ctl.c
+++ b/pp_ctl.c
@@ -3818,15 +3818,14 @@ PP(pp_entereval)
     if (PL_compiling.cop_hints_hash) {
 	Perl_refcounted_he_free(aTHX_ PL_compiling.cop_hints_hash);
     }
-    if (Perl_fetch_cop_label(aTHX_ PL_curcop->cop_hints_hash, NULL, NULL)) {
+    if (Perl_fetch_cop_label(aTHX_ PL_curcop, NULL, NULL)) {
 	/* The label, if present, is the first entry on the chain. So rather
 	   than writing a blank label in front of it (which involves an
 	   allocation), just use the next entry in the chain.  */
 	PL_compiling.cop_hints_hash
 	    = PL_curcop->cop_hints_hash->refcounted_he_next;
 	/* Check the assumption that this removed the label.  */
-	assert(Perl_fetch_cop_label(aTHX_ PL_compiling.cop_hints_hash, NULL,
-				    NULL) == NULL);
+	assert(Perl_fetch_cop_label(aTHX_ &PL_compiling, NULL, NULL) == NULL);
     }
     else
 	PL_compiling.cop_hints_hash = PL_curcop->cop_hints_hash;
diff --git a/proto.h b/proto.h
index 42a769e660..ea9cabaf3e 100644
--- a/proto.h
+++ b/proto.h
@@ -6947,7 +6947,11 @@ PERL_CALLCONV void	Perl_sys_init3(int* argc, char*** argv, char*** env)
 	assert(argc); assert(argv); assert(env)
 
 PERL_CALLCONV void	Perl_sys_term(void);
-PERL_CALLCONV const char *	Perl_fetch_cop_label(pTHX_ struct refcounted_he *const chain, STRLEN *len, U32 *flags);
+PERL_CALLCONV const char *	Perl_fetch_cop_label(pTHX_ COP *const cop, STRLEN *len, U32 *flags)
+			__attribute__nonnull__(pTHX_1);
+#define PERL_ARGS_ASSERT_FETCH_COP_LABEL	\
+	assert(cop)
+
 PERL_CALLCONV void	Perl_store_cop_label(pTHX_ COP *cop, const char *label, STRLEN len, U32 flags)
 			__attribute__nonnull__(pTHX_1)
 			__attribute__nonnull__(pTHX_2);