[patch: handy.c] update Newx API pod to mention PERL_MEM_LOG build opt

Message-ID: <42D31A4A.1020305@divsol.com>

(with some minor tweaks)

p4raw-id: //depot/perl@25115

diff --git a/handy.h b/handy.h
index 8cddbab..72b967e 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -550,18 +550,19 @@ C<id> is an integer id between 0 and 1299 (used to identify leaks).
 =for apidoc Am|void|Newx|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<malloc> function.
 
+In 5.9.3, Newx() and friends replace the older New() API, and drops
+the first parameter, I<x>, a debug aid which allowed callers to identify
+themselves.  This aid has been superceded by a new build option,
+PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>).  The older API is still
+there for use in XS modules supporting older perls.
+
 =for apidoc Am|void|Newxc|void* ptr|int nitems|type|cast
 The XSUB-writer's interface to the C C<malloc> function, with
-cast.
+cast.  See also C<Newx>.
 
 =for apidoc Am|void|Newxz|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<malloc> function.  The allocated
-memory is zeroed with C<memzero>.
-
-In 5.9.3, we removed the 1st parameter, a debug aid, from the api.  It
-was used to uniquely identify each usage of these allocation
-functions, but was deemed unnecessary with the availability of better
-memory tracking tools, valgrind for example.
+memory is zeroed with C<memzero>.  See also C<Newx>.
 
 =for apidoc Am|void|Renew|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<realloc> function.

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index eb5dca9..8dfce33 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -1603,6 +1603,12 @@ Found in file handy.h
 
 The XSUB-writer's interface to the C C<malloc> function.
 
+In 5.9.3, Newx() and friends replace the older New() API, and drops
+the first parameter, I<x>, a debug aid which allowed callers to identify
+themselves.  This aid has been superceded by a new build option,
+PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>).  The older API is still
+there for use in XS modules supporting older perls.
+
        void    Newx(void* ptr, int nitems, type)
 
 =for hackers
@@ -1611,7 +1617,7 @@ Found in file handy.h
 =item Newxc
 
 The XSUB-writer's interface to the C C<malloc> function, with
-cast.
+cast.  See also C<Newx>.
 
        void    Newxc(void* ptr, int nitems, type, cast)
 
@@ -1621,12 +1627,7 @@ Found in file handy.h
 =item Newxz
 
 The XSUB-writer's interface to the C C<malloc> function.  The allocated
-memory is zeroed with C<memzero>.
-
-In 5.9.3, we removed the 1st parameter, a debug aid, from the api.  It
-was used to uniquely identify each usage of these allocation
-functions, but was deemed unnecessary with the availability of better
-memory tracking tools, valgrind for example.
+memory is zeroed with C<memzero>.  See also C<Newx>.
 
        void    Newxz(void* ptr, int nitems, type)