This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Free tied hash iterator state immediately at the `untie` call
[perl5.git] / pod / perldelta.pod
CommitLineData
0382c61d 1=encoding utf8
7b0fb693 2
0382c61d 3=head1 NAME
7b0fb693 4
74f6ed49
MH
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.35.5
2f9090fc 9
b129a266 10=head1 DESCRIPTION
2f9090fc 11
74f6ed49 12This document describes differences between the 5.35.4 release and the 5.35.5
b129a266 13release.
2f9090fc 14
74f6ed49
MH
15If you are upgrading from an earlier release such as 5.35.3, first read
16L<perl5354delta>, which describes differences between 5.35.3 and 5.35.4.
17
18=head1 Notice
19
20XXX Any important notices here
9623941f 21
9e71a8df 22=head1 Core Enhancements
9623941f 23
74f6ed49
MH
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
f79e2ff9 27
74f6ed49 28[ List each enhancement as a =head2 entry ]
f79e2ff9 29
74f6ed49 30=head1 Security
f79e2ff9 31
74f6ed49
MH
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
2f1eff3d 35
74f6ed49 36[ List each security issue as a =head2 entry ]
2f1eff3d 37
74f6ed49 38=head1 Incompatible Changes
0ae3a5cd 39
74f6ed49 40XXX For a release on a stable branch, this section aspires to be:
0ae3a5cd 41
74f6ed49
MH
42 There are no changes intentionally incompatible with 5.XXX.XXX
43 If any exist, they are bugs, and we request that you submit a
44 report. See L</Reporting Bugs> below.
a155cefb 45
74f6ed49 46[ List each incompatible change as a =head2 entry ]
a155cefb 47
74f6ed49 48=head1 Deprecations
a155cefb 49
74f6ed49 50XXX Any deprecated features, syntax, modules etc. should be listed here.
4d374bf1 51
74f6ed49 52=head2 Module removals
4d374bf1 53
74f6ed49 54XXX Remove this section if not applicable.
4d374bf1 55
74f6ed49
MH
56The following modules will be removed from the core distribution in a
57future release, and will at that time need to be installed from CPAN.
58Distributions on CPAN which require these modules will need to list them as
59prerequisites.
e19f9232 60
74f6ed49
MH
61The core versions of these modules will now issue C<"deprecated">-category
62warnings to alert you to this fact. To silence these deprecation warnings,
63install the modules in question from CPAN.
e19f9232 64
74f6ed49
MH
65Note that these are (with rare exceptions) fine modules that you are encouraged
66to continue to use. Their disinclusion from core primarily hinges on their
67necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68not usually on concerns over their design.
fb93d081 69
74f6ed49
MH
70=over
71
72=item XXX
73
74XXX Note that deprecated modules should be listed here even if they are listed
75as an updated module in the L</Modules and Pragmata> section.
e9766ce5 76
73a058ad 77=back
e9766ce5 78
74f6ed49 79[ List each other deprecation as a =head2 entry ]
4d374bf1 80
74f6ed49
MH
81=head1 Performance Enhancements
82
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
85
86[ List each enhancement as an =item entry ]
5799cb34 87
73a058ad 88=over 4
4d374bf1
KE
89
90=item *
91
74f6ed49 92XXX
73a058ad 93
74f6ed49 94=back
e1cd9cd5 95
74f6ed49 96=head1 Modules and Pragmata
e1cd9cd5 97
74f6ed49
MH
98XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
99go here. If Module::CoreList is updated, generate an initial draft of the
100following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
101for important changes should then be added by hand. In an ideal world,
102dual-life modules would have a F<Changes> file that could be cribbed.
e1cd9cd5 103
74f6ed49
MH
104The list of new and updated modules is modified automatically as part of
105preparing a Perl release, so the only reason to manually add entries here is if
106you're summarising the important changes in the module update. (Also, if the
107manually-added details don't match the automatically-generated ones, the
108release manager will have to investigate the situation carefully.)
e1cd9cd5 109
74f6ed49 110[ Within each section, list entries as an =item entry ]
e1cd9cd5 111
74f6ed49
MH
112=head2 New Modules and Pragmata
113
114=over 4
e1cd9cd5
MH
115
116=item *
117
74f6ed49 118XXX Remove this section if not applicable.
e1cd9cd5 119
74f6ed49 120=back
e1cd9cd5 121
74f6ed49
MH
122=head2 Updated Modules and Pragmata
123
124=over 4
e1cd9cd5
MH
125
126=item *
127
74f6ed49 128L<XXX> has been upgraded from version A.xx to B.yy.
e1cd9cd5 129
74f6ed49 130If there was something important to note about this change, include that here.
e1cd9cd5 131
74f6ed49 132=back
e1cd9cd5 133
74f6ed49 134=head2 Removed Modules and Pragmata
e1cd9cd5 135
74f6ed49 136=over 4
e1cd9cd5
MH
137
138=item *
139
74f6ed49 140XXX
e1cd9cd5 141
74f6ed49 142=back
e1cd9cd5 143
74f6ed49 144=head1 Documentation
e1cd9cd5 145
74f6ed49
MH
146XXX Changes to files in F<pod/> go here. Consider grouping entries by
147file and be sure to link to the appropriate page, e.g. L<perlfunc>.
e1cd9cd5 148
74f6ed49 149=head2 New Documentation
e1cd9cd5 150
74f6ed49 151XXX Changes which create B<new> files in F<pod/> go here.
e1cd9cd5 152
74f6ed49 153=head3 L<XXX>
e1cd9cd5 154
74f6ed49 155XXX Description of the purpose of the new file here
e1cd9cd5 156
74f6ed49 157=head2 Changes to Existing Documentation
e1cd9cd5 158
74f6ed49
MH
159We have attempted to update the documentation to reflect the changes
160listed in this document. If you find any we have missed, open an issue
161at L<https://github.com/Perl/perl5/issues>.
e1cd9cd5 162
74f6ed49
MH
163XXX Changes which significantly change existing files in F<pod/> go here.
164However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
165section.
e1cd9cd5 166
74f6ed49 167Additionally, the following selected changes have been made:
e1cd9cd5 168
74f6ed49
MH
169=head3 L<XXX>
170
171=over 4
e1cd9cd5
MH
172
173=item *
174
74f6ed49 175XXX Description of the change here
73a058ad 176
74f6ed49 177=back
3c5ad6a8 178
74f6ed49 179=head1 Diagnostics
3c5ad6a8 180
74f6ed49
MH
181The following additions or changes have been made to diagnostic output,
182including warnings and fatal error messages. For the complete list of
183diagnostic messages, see L<perldiag>.
3c5ad6a8 184
74f6ed49
MH
185XXX New or changed warnings emitted by the core's C<C> code go here. Also
186include any changes in L<perldiag> that reconcile it to the C<C> code.
3c5ad6a8 187
74f6ed49 188=head2 New Diagnostics
e4e803bd 189
74f6ed49
MH
190XXX Newly added diagnostic messages go under here, separated into New Errors
191and New Warnings
e4e803bd 192
74f6ed49 193=head3 New Errors
e1cd9cd5 194
74f6ed49 195=over 4
e1cd9cd5
MH
196
197=item *
198
74f6ed49 199XXX L<message|perldiag/"message">
e1cd9cd5 200
74f6ed49 201=back
e1cd9cd5 202
74f6ed49
MH
203=head3 New Warnings
204
205=over 4
e1cd9cd5
MH
206
207=item *
208
74f6ed49
MH
209XXX L<message|perldiag/"message">
210
211=back
212
213=head2 Changes to Existing Diagnostics
214
215XXX Changes (i.e. rewording) of diagnostic messages go here
216
217=over 4
e1cd9cd5
MH
218
219=item *
220
74f6ed49 221XXX Describe change here
e1cd9cd5 222
9e71a8df 223=back
c068e0be 224
74f6ed49 225=head1 Utility Changes
c068e0be 226
74f6ed49
MH
227XXX Changes to installed programs such as F<perldoc> and F<xsubpp> go here.
228Most of these are built within the directory F<utils>.
c068e0be 229
74f6ed49
MH
230[ List utility changes as a =head2 entry for each utility and =item
231entries for each change
232Use L<XXX> with program names to get proper documentation linking. ]
c068e0be 233
74f6ed49 234=head2 L<XXX>
c068e0be 235
9e71a8df 236=over 4
c068e0be
NB
237
238=item *
239
74f6ed49 240XXX
6521d5bb 241
9e71a8df 242=back
c068e0be 243
74f6ed49 244=head1 Configuration and Compilation
73a058ad 245
74f6ed49
MH
246XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
247go here. Any other changes to the Perl build process should be listed here.
248However, any platform-specific changes should be listed in the
249L</Platform Support> section, instead.
73a058ad 250
74f6ed49 251[ List changes as an =item entry ].
9e71a8df
NB
252
253=over 4
9623941f 254
2f19223f
JK
255=item *
256
74f6ed49 257XXX
c068e0be 258
9e71a8df 259=back
c068e0be 260
74f6ed49 261=head1 Testing
9623941f 262
74f6ed49
MH
263XXX Any significant changes to the testing of a freshly built perl should be
264listed here. Changes which create B<new> files in F<t/> go here as do any
265large changes to the testing harness (e.g. when parallel testing was added).
266Changes to existing files in F<t/> aren't worth summarizing, although the bugs
267that they represent may be covered elsewhere.
9623941f 268
74f6ed49 269XXX If there were no significant test changes, say this:
9623941f 270
74f6ed49
MH
271Tests were added and changed to reflect the other additions and changes
272in this release.
6521d5bb 273
74f6ed49 274XXX If instead there were significant changes, say this:
6577de2f 275
74f6ed49
MH
276Tests were added and changed to reflect the other additions and
277changes in this release. Furthermore, these significant changes were
278made:
9623941f 279
74f6ed49 280[ List each test improvement as an =item entry ]
73a058ad
KE
281
282=over 4
283
74f6ed49 284=item *
73a058ad 285
74f6ed49 286XXX
73a058ad 287
74f6ed49 288=back
73a058ad 289
74f6ed49 290=head1 Platform Support
73a058ad 291
74f6ed49 292XXX Any changes to platform support should be listed in the sections below.
73a058ad 293
74f6ed49
MH
294[ Within the sections, list each platform as an =item entry with specific
295changes as paragraphs below it. ]
73a058ad 296
74f6ed49 297=head2 New Platforms
73a058ad 298
74f6ed49
MH
299XXX List any platforms that this version of perl compiles on, that previous
300versions did not. These will either be enabled by new files in the F<hints/>
301directories, or new subdirectories and F<README> files at the top level of the
302source tree.
00164771 303
74f6ed49 304=over 4
00164771 305
74f6ed49
MH
306=item XXX-some-platform
307
308XXX
73a058ad
KE
309
310=back
311
74f6ed49
MH
312=head2 Discontinued Platforms
313
314XXX List any platforms that this version of perl no longer compiles on.
73a058ad 315
9623941f
RS
316=over 4
317
74f6ed49 318=item XXX-some-platform
9623941f 319
74f6ed49 320XXX
73a058ad 321
74f6ed49
MH
322=back
323
324=head2 Platform-Specific Notes
73a058ad 325
74f6ed49
MH
326XXX List any changes for specific platforms. This could include configuration
327and compilation changes or changes in portability/compatibility. However,
328changes within modules for platforms should generally be listed in the
329L</Modules and Pragmata> section.
73a058ad 330
ecbeaca5 331=over 4
73a058ad 332
74f6ed49 333=item XXX-some-platform
73a058ad 334
74f6ed49 335XXX
6521d5bb 336
74f6ed49
MH
337=back
338
339=head1 Internal Changes
340
341XXX Changes which affect the interface available to C<XS> code go here. Other
342significant internal changes for future core maintainers should be noted as
343well.
6521d5bb 344
74f6ed49
MH
345[ List each change as an =item entry ]
346
347=over 4
9e71a8df 348
ecbeaca5
MH
349=item *
350
74f6ed49 351XXX
9e71a8df 352
ecbeaca5 353=back
73a058ad 354
74f6ed49
MH
355=head1 Selected Bug Fixes
356
357XXX Important bug fixes in the core language are summarized here. Bug fixes in
358files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
73a058ad 359
74f6ed49 360[ List each fix as an =item entry ]
9623941f 361
9e71a8df 362=over 4
e89aef54 363
9e71a8df 364=item *
a346264f 365
71e2181f
NC
366Calling C<untie> on a tied hash that is partway through iteration now frees the
367iteration state immediately.
368
369Iterating a tied hash causes perl to store a copy of the current hash key to
370track the iteration state, with this stored copy passed as the second parameter
371to C<NEXTKEY>. This internal state is freed immediately when tie hash iteration
372completes, or if the hash is destroyed, but due to an implementation oversight,
373it was not freed if the hash was untied. In that case, the internal copy of the
374key would persist until the earliest of
375
376=over 4
377
378=item 1
379
380C<tie> was called again on the same hash
381
382=item 2
383
384The (now untied) hash was iterated (ie passed to any of C<keys>, C<values> or
385C<each>)
386
387=item 3
388
389The hash was destroyed.
390
391=back
392
393This inconsistency is now fixed - the internal state is now freed immediately by
394C<untie>.
395
396As the precise timing of this behaviour can be observed with pure Perl code
397(the timing of C<DESTROY> on objects returned from C<FIRSTKEY> and C<NEXTKEY>)
398it's just possible that some code is sensitive to it.
e89aef54 399
74f6ed49 400=back
e89aef54 401
74f6ed49 402=head1 Known Problems
d92691c6 403
74f6ed49
MH
404XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
405tests that had to be C<TODO>ed for the release would be noted here. Unfixed
406platform specific bugs also go here.
407
408[ List each fix as an =item entry ]
ecbeaca5 409
74f6ed49 410=over 4
4d374bf1 411
73a058ad 412=item *
4d374bf1 413
74f6ed49 414XXX
4d374bf1 415
73a058ad 416=back
4d374bf1 417
74f6ed49 418=head1 Errata From Previous Releases
73a058ad 419
74f6ed49 420=over 4
73a058ad 421
74f6ed49 422=item *
4d374bf1 423
74f6ed49
MH
424XXX Add anything here that we forgot to add, or were mistaken about, in
425the perldelta of a previous release.
ecbeaca5 426
74f6ed49 427=back
ecbeaca5 428
74f6ed49 429=head1 Obituary
ecbeaca5 430
74f6ed49
MH
431XXX If any significant core contributor or member of the CPAN community has
432died, add a short obituary here.
ecbeaca5 433
74f6ed49 434=head1 Acknowledgements
ecbeaca5 435
74f6ed49 436XXX Generate this with:
b129a266 437
74f6ed49 438 perl Porting/acknowledgements.pl v5.35.4..HEAD
8424e368 439
44691e6f
AB
440=head1 Reporting Bugs
441
5b68d8ff
SH
442If you find what you think is a bug, you might check the perl bug database
443at L<https://github.com/Perl/perl5/issues>. There may also be information at
46a21c0a 444L<http://www.perl.org/>, the Perl Home Page.
44691e6f 445
8166b4e0 446If you believe you have an unreported bug, please open an issue at
0382c61d 447L<https://github.com/Perl/perl5/issues>. Be sure to trim your bug down to a
8166b4e0 448tiny but sufficient test case.
44691e6f 449
87c118b9 450If the bug you are reporting has security implications which make it
8166b4e0 451inappropriate to send to a public issue tracker, then see
5b68d8ff
SH
452L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
453for details of how to report the issue.
44691e6f 454
390ae6f9
S
455=head1 Give Thanks
456
5b68d8ff
SH
457If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
458you can do so by running the C<perlthanks> program:
390ae6f9
S
459
460 perlthanks
461
462This will send an email to the Perl 5 Porters list with your show of thanks.
463
44691e6f
AB
464=head1 SEE ALSO
465
e08634c5
SH
466The F<Changes> file for an explanation of how to view exhaustive details on
467what changed.
44691e6f
AB
468
469The F<INSTALL> file for how to build Perl.
470
471The F<README> file for general stuff.
472
473The F<Artistic> and F<Copying> files for copyright information.
474
475=cut