| Store | Cart

[perl #122368] [PATCH] improve docs about mortal in perlguts

From: bulk88 (via RT) <perl...@perl.org>
Tue, 22 Jul 2014 08:35:48 -0700
# New Ticket Created by  bulk88 
# Please include the string:  [perl #122368]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org/Ticket/Display.html?id=122368 >


This is a bug report for perl from bul...@hotmail.com,
generated with the help of perlbug 1.40 running under perl 5.21.2.


-----------------------------------------------------------------
[Please describe your issue here]

Unsmoked. See attached patch.

[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
    category=docs
    severity=low
---
Site configuration information for perl 5.21.2:

Configured by Owner at Fri Jul 11 00:44:08 2014.

Summary of my perl5 (revision 5 version 21 subversion 2) configuration:
  Derived from: ecafd7654a8d1bc705e8fe0cd3c89044374db045
  Ancestor: 6e9f2f2d7d7f6ae8cf72ada5a8bf7781fba14273
  Platform:
    osname=MSWin32, osvers=5.1, archname=MSWin32-x86-multi-thread
    uname=''
    config_args='undef'
    hint=recommended, useposix=true, d_sigaction=undef
    useithreads=define, usemultiplicity=define
    use64bitint=undef, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cl', ccflags ='-nologo -GF -W3 -Od -MD -Zi -DDEBUGGING -DWIN32 
-D_CONSOLE -DNO_STRICT  -DPERL_TEXTMODE_SCRIPTS 
-DPERL_HASH_FUNC_ONE_AT_A_TIME -DPERL_IMPLICIT_CONTEXT 
-DPERL_IMPLICIT_SYS -DUSE_PERLIO -D_USE_32BIT_TIME_T',
    optimize='-Od -MD -Zi -DDEBUGGING',
    cppflags='-DWIN32'
    ccversion='13.10.6030', gccversion='', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
    d_longlong=undef, longlongsize=8, d_longdbl=define, longdblsize=8
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='__int64', 
lseeksize=8
    alignbytes=8, prototype=define
  Linker and Libraries:
    ld='link', ldflags ='-nologo -nodefaultlib -debug  
-libpath:"c:\perl521\lib\CORE"  -machine:x86'
    libpth="C:\Program Files\Microsoft Visual Studio .NET 2003\VC7\lib"
    libs=oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib  
comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib  
netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib  version.lib 
odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib
    perllibs=oldnames.lib kernel32.lib user32.lib gdi32.lib 
winspool.lib  comdlg32.lib advapi32.lib shell32.lib ole32.lib 
oleaut32.lib  netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib  
version.lib odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib
    libc=msvcrt.lib, so=dll, useshrplib=true, libperl=perl521.lib
    gnulibc_version=''
  Dynamic Linking:
    dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' '
    cccdlflags=' ', lddlflags='-dll -nologo -nodefaultlib -debug  
-libpath:"c:\perl521\lib\CORE"  -machine:x86'

Locally applied patches:
    uncommitted-changes
    22eb0703e4f1ca0305ca22390770b019a4b0ec4c
    ab36ae0a3ee81e650c6775a6e779fd961d14a2df

---
@INC for perl 5.21.2:
    C:/perl521/site/lib
    C:/perl521/lib
    .

---
Environment for perl 5.21.2:
    HOME (unset)
    LANG (unset)
    LANGUAGE (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=C:\perl521\bin;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\IDE;C:\Program Files\Microsoft Visual Studio .NET 
2003\VC7\BIN;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\Tools;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\Tools\bin\prerelease;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\system32\wbem;
    PERL_BADLANG (unset)
    SHELL (unset)


>From 543c0e688ee3c5a452b9203e04eee8a0f448ecfa Mon Sep 17 00:00:00 2001
From: Daniel Dragan <bul...@hotmail.com>
Date: Tue, 22 Jul 2014 11:33:06 -0400
Subject: [PATCH] improve docs about mortal in perlguts

---
 pod/perlguts.pod |   16 +++++++++++++---
 1 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 105e817..b8d2d77 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -787,7 +787,11 @@ manipulated with the following macros:
 
     int SvREFCNT(SV* sv);
     SV* SvREFCNT_inc(SV* sv);
+    SV* SvREFCNT_inc_NN(SV* sv);
+    void SvREFCNT_inc_void(SV* sv);
+    /* see perlapi for other variants */
     void SvREFCNT_dec(SV* sv);
+    void SvREFCNT_dec_NN(SV* sv);
 
 However, there is one other function which manipulates the reference
 count of its argument.  The C<newRV_inc> function, you will recall,
@@ -822,13 +826,16 @@ See L<perlcall> and L<perlxs> for more details on these macros.
 
 "Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
 However, if you mortalize a variable twice, the reference count will
-later be decremented twice.
+later be decremented twice.  Mortal can be thought of as attached a SV to
+the current scope of the Perl stack (but not putting the SV on the Perl stack),
+and the SV will be freeded if nothing else wants it, when the scope is left.
+Mortal is similar to a C++ smart pointer.
 
 "Mortal" SVs are mainly used for SVs that are placed on perl's stack.
 For example an SV which is created just to pass a number to a called sub
 is made mortal to have it cleaned up automatically when it's popped off
 the stack.  Similarly, results returned by XSUBs (which are pushed on the
-stack) are often made mortal.
+stack) are often made mortal; the few exceptions are listed further down.
 
 To create a mortal variable, use the functions:
 
@@ -858,7 +865,10 @@ as deferred C<SvREFCNT_dec> should help to minimize such problems.
 For example if you are passing an SV which you I<know> has a high enough REFCNT
 to survive its use on the stack you need not do any mortalization.
 If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or
-making a C<sv_mortalcopy> is safer.
+making a C<sv_mortalcopy> is safer.  A real example would be getting a SV * from
+C<get_sv>. In that case, the SV is owned by the package namespace.  If you just
+mortal the package SV, you will probably free the SV in the glob, causing a perl
+panic or crash.
 
 The mortal routines are not just for SVs; AVs and HVs can be
 made mortal by passing their address (type-casted to C<SV*>) to the
-- 
1.7.9.msysgit.0


Recent Messages in this Thread
bulk88 (via RT) Jul 22, 2014 03:35 pm
Dave Mitchell Jul 23, 2014 01:33 pm
Tony Cook via RT Jul 22, 2014 11:37 pm
H.Merijn Brand Jul 23, 2014 06:49 am
Messages in this thread