DEPRECATED.pod

   1 # $Id$
   2
   3 =head1 Purpose
   4
   5 Provide a list of deprecated and experimental items in parrot.
   6 All items in this list should have a corresponding Trac ticket[1].
   7
   8 =head1 Experimental Status
   9
  10 These features are not considered supported, even though they may
  11 have shipped in a supported release of parrot[2]. Use them at your own
  12 risk, as they can be removed or changed in any release. These
  13 items are marked below with C<[experimental]>.
  14
  15 =head1 Deprecated Status
  16
  17 Please see F<docs/project/support_policy.pod> for the parrot
  18 project's policy regarding deprecated features.
  19
  20 Each item shows the first release in which it is eligible for removal, e.g.
  21 C<[eligible in 1.5]>.  If the release listed is one that has already
  22 shipped, this feature may be removed in B<any> upcoming release, and
  23 you should no longer rely on it.
  24
  25 If you find a feature you once used was removed after a deprecation
  26 cycle, L<https://trac.parrot.org/parrot/wiki/Deprecation>. Otherwise
  27 please open a documentation ticket via Trac[1].
  28
  29 =head1 Are you using any Deprecated Features?
  30
  31 When running parrot, you can receive warnings about deprecations.
  32 Either run parrot with the C<-w> option to enable all warnings, or
  33 deprecations specifically by including this snippet:
  34
  35 =begin PIR_FRAGMENT
  36
  37  .include 'warnings.pasm'
  38  warningson .PARROT_WARNINGS_DEPRECATED_FLAG
  39
  40 =end PIR_FRAGMENT
  41
  42 =head1 PMCS
  43
  44 =over 4
  45
  46 =item GzipHandle [experimental]
  47
  48 L<https://trac.parrot.org/parrot/ticket/1580>
  49
  50 =item PackfileDebug [experimental]
  51
  52 L<https://trac.parrot.org/parrot/ticket/1599>
  53
  54 =item CodeString [eligible in 2.7]
  55
  56 L<http://trac.parrot.org/parrot/ticket/1633>
  57
  58 =item multiple dispatch within core PMCs [eligible in 1.1]
  59
  60 L<https://trac.parrot.org/parrot/ticket/452>
  61
  62 =item Method stdhandle in ParrotInterpreter [experimental]
  63
  64 L<https://trac.parrot.org/parrot/ticket/264>
  65
  66 =item Overriding vtable invoke in PIR objects [experimental]
  67
  68 The VTABLE invoke in object.pmc puts SELF at the start of the
  69 signature call arguments when there is no current object and is
  70 not already here. This allows the usage of $P0() instead of $P0($P0).
  71
  72 L<https://trac.parrot.org/parrot/ticket/103>
  73
  74 =item UnManagedStruct handling nested structure [eligible in 2.4]
  75
  76 UnManagedStruct will be simplified to only support flat structures. This means
  77 that elements which themselves have structure - struct pointers and function
  78 pointers will be stored as C<void *> and C<void (*)(void)> respectively. To use
  79 these, they will need to be cast to the appropriate signature on access.
  80
  81 L<https://trac.parrot.org/parrot/ticket/1551>
  82
  83 =item UnManagedStruct initializer structure [eligible in 2.4]
  84
  85 The initializer structure will cease to be an array of triples. In stead, an
  86 array of flags (no counts or offsets), or a string representation of the same
  87 information may be used.
  88
  89 L<https://trac.parrot.org/parrot/ticket/1552>
  90
  91 =item UnManagedStruct get_integer, set_integer_native [eligible in 2.4]
  92
  93 These will no longer refer to the byte length of the buffer, but to the number
  94 of times the struct is repeated; emulating an array of structs.
  95
  96 L<https://trac.parrot.org/parrot/ticket/1553>
  97
  98 =item ManagedStruct reallocations based on shape changes [eligible in 2.4]
  99
 100 Since shape changes may simply be used for re-interpreting data, and may also
 101 occur in several steps, re-allocating after any one shape change may be
 102 undesirable. In stead, an explicit allocate/reallocate method will be provided.
 103
 104 L<https://trac.parrot.org/parrot/ticket/1554>
 105
 106 =item Auto-vivification of nested aggregates [eligible in 2.4]
 107
 108 E.g.
 109
 110   $P0 = new ['Hash']
 111   $S1 = $P0['foo';'bar';'baz']
 112
 113 will not auto-vivify nested hashes and return PMCNULL early.
 114
 115 L<https://trac.parrot.org/parrot/ticket/1561>
 116
 117 =item Method lower on String [eligible in 2.7]
 118
 119 Use the downcase opcode or subclass with a method name consistent with your
 120 HLL.
 121
 122 L<http://trac.parrot.org/parrot/ticket/1606>
 123
 124 =item Method unescape on String [experimental]
 125
 126 This is a helper method for testing of Parrot_str_unescape_string.
 127
 128 L<https://trac.parrot.org/parrot/ticket/1628>
 129
 130 =item logical_* vtables [eligiblie in 2.7]
 131
 132 These can be replaced by C<get_bool> and intval ops unless you're using them for
 133 things that aren't really logical ops (don't do that!).
 134
 135 Logical vtables are removed in r49012, and logical ops on PMCs are converted to
 136 use C<get_bool> internally. Rakudo seems to depend on logical ops on PMCs.
 137
 138 L<https://trac.parrot.org/parrot/ticket/1655>
 139
 140 =item Method getpid on ParrotInterpreter [experimental]
 141
 142 Used to test the experimental function Parrot_getpid
 143
 144 L<https://trac.parrot.org/parrot/ticket/1564>
 145
 146 =item Behavior of Parrot::Pmc2c::PMC::add_method() [eligible in 2.10]
 147
 148 Duplicated vtable functions currently generate only a warning; after deadline,
 149 they will cause a C<die> and failure to build Parrot or any HLL
 150 using this method.
 151
 152 L<http://trac.parrot.org/parrot/ticket/1785>
 153
 154 =back
 155
 156 =head1 Opcodes
 157
 158 =over 4
 159
 160 =item charset, charsetname, find_charset, trans_charset [eligible in 2.10]
 161
 162 L<https://trac.parrot.org/parrot/ticket/1778>
 163
 164 These opcodes will be removed. The corresponding encoding opcodes should be
 165 used instead.
 166
 167 =item fixed_8 encoding [eligible in 2.10]
 168
 169 L<https://trac.parrot.org/parrot/ticket/1778>
 170
 171 The 'fixed_8' encoding is going away. Use 'ascii' instead. If you want to test
 172 for a fixed_8 encoding, you have to compare the encoding to 'ascii',
 173 'iso-8859-1' and 'binary' separately.
 174
 175 =item open and close opcodes will be removed [eligible in 2.7]
 176
 177 L<https://trac.parrot.org/parrot/ticket/1697>
 178
 179 These opcodes will be removed. The open/close methods on File or
 180 the FileHandle PMC should be used instead.
 181
 182 =item get_addr and set_addr [eligible in 1.5]
 183
 184 L<https://trac.parrot.org/parrot/ticket/218>
 185
 186 These opcodes are being repurposed. They will always return a unique memory
 187 address of the PMC. Uses of get_addr and set_addr that would set label values
 188 for Sub, Exception, and related PMC types will instead be handled by
 189 get_label and set_label.
 190
 191 =item get_results opcode order and features [eligible in 2.1]
 192
 193 get_results no longer used to fetch exception object.
 194
 195 L<https://trac.parrot.org/parrot/ticket/1406>
 196
 197 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
 198
 199 Ability to get the string name of the current GC core from the interpinfo_s_i.
 200 See r43900 and r43904 for details.
 201
 202 L<https://trac.parrot.org/parrot/ticket/1581>
 203
 204 =item NCI_FB_CB and NCI_FB_UD in iglobals [experimental]
 205
 206 Hooks allowing a runtime-loadable dynamic frame builder.
 207
 208 L<https://trac.parrot.org/parrot/ticket/1582>
 209
 210 =item loadlib_p_s_p [experimental]
 211
 212 Ability to use non-default dynamic loading behaviour.
 213
 214 L<https://trac.parrot.org/parrot/ticket/1583>
 215
 216 =item new_callback_p_p_p_s [eligible in 2.4]
 217
 218 To be replaced with new_callback_p_p_p_p_s.
 219
 220 L<https://trac.parrot.org/parrot/ticket/1548>
 221
 222 =item dlfunc and new_callback signature string format [eligible in 2.4]
 223
 224 These will be changed to allow more flexibility in types.
 225
 226 L<https://trac.parrot.org/parrot/ticket/1565>
 227
 228 =item find_lex [eligible in 2.4]
 229
 230 find_lex will not throw exception for non-existing lexicals.
 231
 232 L<https://trac.parrot.org/parrot/ticket/1207>
 233
 234 =item inplace string updates. [eligible in 2.4]
 235
 236 All "inplace" string update ops are deprecated. E.g. "chopn_s", etc.
 237 Part of COW removal.
 238
 239 L<https://trac.parrot.org/parrot/ticket/1540>
 240
 241 =item find_codepoint [experimental]
 242
 243 Intended to replace the CodeString charname_to_ord method.
 244
 245 L<https://trac.parrot.org/parrot/ticket/1629>
 246
 247 =item All opcodes that modify non-argument registers. [eligible in 2.7]
 248
 249 E.g. "cleari", etc.
 250
 251 L<https://trac.parrot.org/parrot/ticket/1642>
 252
 253 =item exchange [eligible in 2.7]
 254
 255 This op is too low level for Parrot in its current form.
 256
 257 L<https://trac.parrot.org/parrot/ticket/1643>
 258
 259 =item finalize [experimental]
 260
 261 Finalize exception handler, unrolling inner runloops if needed.
 262
 263 L<https://trac.parrot.org/parrot/ticket/1635>
 264
 265 =item logical PMC ops [eligible in 2.7]
 266
 267 These fall out from the logical vtables deprecation.
 268
 269 L<https://trac.parrot.org/parrot/ticket/1655>
 270
 271 =item errorson, errorsoff operations [eligible in 2.10]
 272
 273 The C<.PARROT_ERRORS_GLOBAL_FLAG> flag will be eliminated. It is not used by Parrot.
 274
 275 =back
 276
 277 =head1 Bytecode
 278
 279 =over 4
 280
 281 =item packfile structure [experimental]
 282
 283 L<https://trac.parrot.org/parrot/ticket/451>
 284
 285 =item opcode numbering [experimental]
 286
 287 L<https://trac.parrot.org/parrot/ticket/451>
 288
 289 =item PMC numbering [experimental]
 290
 291 L<https://trac.parrot.org/parrot/ticket/451>
 292
 293 =back
 294
 295 =head1 Debugger
 296
 297 Assigning to registers [experimental]
 298
 299 =head1 PIR syntax
 300
 301 =over 4
 302
 303 =item Assignment syntax with opcodes [eligible in 1.1]
 304
 305 L<https://trac.parrot.org/parrot/ticket/906>
 306
 307 =item continuation-based ExceptionHandlers [eligible in 2.1]
 308
 309 L<https://trac.parrot.org/parrot/ticket/1091>
 310
 311 =item implicit optional named parameters [eligible in 2.1]
 312
 313 L<https://trac.parrot.org/parrot/ticket/1103>
 314
 315 =item :unique_reg flag [eligible in 2.7]
 316
 317 L<https://trac.parrot.org/parrot/ticket/1622>
 318
 319 =item .nci_call [eligible in 2.7]
 320
 321 As of the latest PCC changes, there is nothing special about calling an NCI sub.
 322
 323 L<https://trac.parrot.org/parrot/ticket/1623>
 324
 325 =item .meth_call [eligible in 2.7]
 326
 327 As of the latest PCC changes, this does nothing different from '.call'.
 328
 329 L<https://trac.parrot.org/parrot/ticket/1624>
 330
 331 =item :main Sub behaviour and selection. [eligible in 2.7]
 332
 333 Currently, if no :main sub is found, the first .sub in a file is used as
 334 main. Also, arguments are passed to the main sub regardless of the .param
 335 declarations in that sub.
 336
 337 After this change, if no sub is marked with :main, an exception will be
 338 raised. Multiple :main declarations will be still be allowed, and all but the
 339 first will be ignored.
 340
 341 This change will also force all subs, including :main, to have their
 342 arguments checked - to allow an arbitrary number of arguments, have
 343 this be the only .param declaration in the sub.
 344
 345  .param pmc args :slurpy
 346
 347
 348 L<https://trac.parrot.org/parrot/ticket/1033>
 349 L<https://trac.parrot.org/parrot/ticket/1704>
 350 L<https://trac.parrot.org/parrot/ticket/1705>
 351
 352 =back
 353
 354 =head1 Functions
 355
 356 =over 4
 357
 358 =item mmd_cvt_to_types [eligible in 1.1]
 359
 360 L<https://trac.parrot.org/parrot/ticket/907>
 361
 362 =item C API coding standards cleanup [eligible in 1.1]
 363
 364 All C API functions that aren't currently named according to the
 365 'Parrot_<system>_*' scheme will be renamed. A list of renamed
 366 functions will be kept in the ticket at:
 367
 368 L<https://trac.parrot.org/parrot/ticket/443>
 369
 370 =item PMC Attributes Allocation Functions [experimental]
 371
 372  Parrot_gc_allocate_pmc_attributes
 373  Parrot_gc_free_pmc_attributes
 374
 375 These items and related helper functions are added as experimental support
 376 for L<https://trac.parrot.org/parrot/ticket/1506>
 377
 378 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 379
 380 All STRING modification functions will return a STRING pointer; capture and use
 381 this rather than relying on in-place modification of an existing pointer.
 382
 383 L<https://trac.parrot.org/parrot/ticket/1584>
 384
 385 =item STRING COW [eligible in 2.4]
 386
 387 COW strings are to be removed. All "inplace" string modification
 388 functions and all "inplace" string ops are deprecated.
 389
 390 L<https://trac.parrot.org/parrot/ticket/1540>
 391
 392 =item Parrot_str_unescape_string [experimental]
 393
 394 This function is an experimental addition to enhance and maybe replace
 395 Parrot_str_unescape
 396
 397 L<https://trac.parrot.org/parrot/ticket/1628>
 398
 399 =item Parrot_getpid [experimental]
 400
 401 Get process id, experimental.
 402
 403 L<https://trac.parrot.org/parrot/ticket/1564>
 404
 405 =back
 406
 407 =head1 Compiler tools
 408
 409 =head2 Parrot Grammar Engine (PGE)
 410
 411 =over 4
 412
 413 =item Action methods in rules
 414
 415 Per Synopsis 5, all regexes will have an implied {*} token at the
 416 end which cause invocation of an action method if a C<:action>
 417 object is supplied.
 418
 419 L<https://trac.parrot.org/parrot/ticket/843>
 420
 421 =back
 422
 423 =head2 Parrot Compiler Toolkit
 424
 425 =over 4
 426
 427 =item PCT::HLLCompiler stages [eligible in 1.1]
 428
 429 The interface of various methods for adding, removing, and modifying
 430 the list stages in a PCT::HLLCompiler object is subject to change.
 431 The existing actual stages will remain; only the mechanism for specifying
 432 the order of individual stages is likely to change.
 433
 434 L<https://trac.parrot.org/parrot/ticket/462>
 435
 436 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 437
 438 In order to facilitate using PCT::HLLCompiler with test harnesses,
 439 the C<command_line> method of PCT::HLLCompiler object exits silently
 440 if it detects that it is being run in a sample run from Perl's
 441 Test::Harness.  Currently this detection is done by checking the
 442 second command line argument for "@INC"; future releases may
 443 use a different detection mechanism or eliminate it altogether.
 444
 445 L<https://trac.parrot.org/parrot/ticket/463>
 446
 447 =item PAST::Val node generation [eligible in 1.5]
 448
 449 The PAST::Compiler may generate the code for PAST::Val nodes
 450 (i.e., constants) at the beginning of the block (Parrot sub) instead
 451 of the location where they occur in the PAST tree.
 452
 453 L<https://trac.parrot.org/parrot/ticket/868>
 454
 455 =item Meta-model implementation used by PCT [eligible in 2.7]
 456
 457 PCT is set to switch to a new meta-model implementation for its classes
 458 and objects. This will most likely only affect those who rely on the
 459 interface of what is returned from .HOW, or rely on PCT objects exhibiting
 460 various other peculiarities of the P6object implementation. (Even when that
 461 is the case, the HOW API will not be changing too drastically, so for most
 462 PCT users there should be little to no upheavel.)
 463
 464 =back
 465
 466 =head1 Parrot library
 467
 468 =over 4
 469
 470 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 471
 472 L<https://trac.parrot.org/parrot/ticket/1429>
 473
 474 A way to provide an equivalent of -L and -I parrot command line options
 475 to language that doesn't support it.
 476
 477 =item Protoobject [eligible in 2.7]
 478
 479 Use P6Object instead.
 480
 481 L<http://trac.parrot.org/parrot/ticket/1337>
 482
 483 =item Archive::Tar & Archive::Zip [experimental]
 484
 485 L<https://trac.parrot.org/parrot/ticket/1598>
 486
 487 =item LWP, HTTP::Message, URI & URI::Escape [experimental]
 488
 489 L<http://trac.parrot.org/parrot/ticket/1637>
 490
 491 =item JSON and Config;JSON [eligible in 1.5]
 492
 493 L<https://trac.parrot.org/parrot/ticket/508>
 494
 495 =item Cross-HLL library loading [experimental]
 496
 497 L<https://trac.parrot.org/parrot/ticket/754>
 498
 499 =item OpenGL bindings and libraries [experimental]
 500
 501 L<https://trac.parrot.org/parrot/ticket/852>
 502
 503 =back
 504
 505 =head1 Experimental
 506
 507 =over 4
 508
 509 =item Threads and Parallelism [experimental]
 510
 511 L<https://trac.parrot.org/parrot/ticket/1601>
 512
 513 =back
 514
 515 =head1 Footnotes
 516
 517 =over 4
 518
 519 =item 1
 520
 521 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 522
 523 =item 2
 524
 525 For an item to be considered experimental, it can B<never> have shipped in
 526 a supported release without the C<[experimental]> tag; otherwise, it must be
 527 deprecated normally before removal or incompatible change.
 528
 529 =back
 530
 531 =cut