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

[bulk88 (via RT)]

# 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 ***@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)

[Tony Cook via RT]

Post by bulk88 (via RT)
Unsmoked. See attached patch.

"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

Should probably be "Mortalization can be thought of attaching an SV to ..."[1]

+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.

There's a enough differences that this comparison might be confusing. Anyone else?

Tony

[1] I pronounce SV as ess-vee, so "an" instead of "a", perlguts uses "a SV" once, "an SV" several times

---
via perlbug: queue: perl5 status: new
https://rt.perl.org/Ticket/Display.html?id=122368

[H.Merijn Brand]

Post by Tony Cook via RT

Post by bulk88 (via RT)
Unsmoked. See attached patch.

"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
Should probably be "Mortalization can be thought of attaching an SV to ..."[1]
+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.

freeded?

Post by Tony Cook via RT
+Mortal is similar to a C++ smart pointer.
There's a enough differences that this comparison might be confusing.
Anyone else?
Tony
[1] I pronounce SV as ess-vee, so "an" instead of "a", perlguts uses
"a SV" once, "an SV" several times
---
via perlbug: queue: perl5 status: new
https://rt.perl.org/Ticket/Display.html?id=122368

[Dave Mitchell]

Post by Tony Cook via RT
-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.

I'm not particularly keen on this phrasing and am not sure what it's
trying to say. The "Perl stack" (i.e. PL_stack_sp) doesn't really have a
scope as such. Tmps are freed based on the scope of the tmps stack, and is
triggered by a call to FREETMPS, which is done in many places, often only
marginally connected to PL_stack_sp. Its possible for the Perl_stack
frame to be popped and no temps freed and vice versa.

[bulk88 via RT]

Post by Tony Cook via RT

Post by bulk88 (via RT)
Unsmoked. See attached patch.

"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
Should probably be "Mortalization can be thought of attaching an SV to
..."[1]
+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.
There's a enough differences that this comparison might be confusing.
Anyone else?
Tony
[1] I pronounce SV as ess-vee, so "an" instead of "a", perlguts uses
"a SV" once, "an SV" several times

-freeded fixed,
-analogy to "perl stack" removed and replaced with another analogy
-a replace with an
-example expanded of when it is safe to return an SV on perl stack without sv_2mortal

[Tony Cook via RT]

On Tue Apr 28 12:35:10 2015, bulk88 wrote:
"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. Mortalization can be thought of attaching an SV to
+the current scope, or current executing statement of Perl code, and upon the
+change to the next Perl language scope (C<}>), or next Perl language statement
+(C<;>), or XS synthesis of those 2 Perl langauge concepts, the SV will be
+freed if nothing else wanted to retain the SV. Mortal is similar to a C++
+smart pointer.

It might be better to just say that FREETMPS is called in those places.

Tony

---
via perlbug: queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=122368

[bulk88 via RT]

Post by Tony Cook via RT
"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. Mortalization can be thought of
attaching an SV to
+the current scope, or current executing statement of Perl code, and
upon the
+change to the next Perl language scope (C<}>), or next Perl language
statement
+(C<;>), or XS synthesis of those 2 Perl langauge concepts, the SV
will be
+freed if nothing else wanted to retain the SV. Mortal is similar to
a C++
+smart pointer.
It might be better to just say that FREETMPS is called in those
places.
Tony

I think saying only "calls FREETMPS" is unhelpful. FREETMPS is another macro. Documenting any 2 macros as being the opposites of each other, doesn't say what they are, or when to use them. I want to connect the mortal concept of XS code to something in PP code, that a XS newbie will understand, since all XS programmers come from PP programmers (I hope).