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 L<https://trac.parrot.org/parrot/ticket/1655>
 136
 137 =item Method getpid on ParrotInterpreter [experimental]
 138
 139 Used to test the experimental function Parrot_getpid
 140
 141 L<https://trac.parrot.org/parrot/ticket/1564>
 142
 143 =item Behavior of Parrot::Pmc2c::PMC::add_method() [eligible in 2.10]
 144
 145 Duplicated vtable functions currently generate only a warning; after deadline,
 146 they will cause a C<die> and failure to build Parrot or any HLL
 147 using this method.
 148
 149 L<http://trac.parrot.org/parrot/ticket/1785>
 150
 151 =back
 152
 153 =head1 Opcodes
 154
 155 =over 4
 156
 157 =item charset, charsetname, find_charset, trans_charset [eligible in 2.10]
 158
 159 L<https://trac.parrot.org/parrot/ticket/1778>
 160
 161 These opcodes will be removed. The corresponding encoding opcodes should be
 162 used instead.
 163
 164 =item fixed_8 encoding [eligible in 2.10]
 165
 166 L<https://trac.parrot.org/parrot/ticket/1778>
 167
 168 The 'fixed_8' encoding is going away. Use 'ascii' instead. If you want to test
 169 for a fixed_8 encoding, you have to compare the encoding to 'ascii',
 170 'iso-8859-1' and 'binary' separately.
 171
 172 =item open and close opcodes will be removed [eligible in 2.7]
 173
 174 L<https://trac.parrot.org/parrot/ticket/1697>
 175
 176 These opcodes will be removed. The open/close methods on File or
 177 the FileHandle PMC should be used instead.
 178
 179 =item get_addr and set_addr [eligible in 1.5]
 180
 181 L<https://trac.parrot.org/parrot/ticket/218>
 182
 183 These opcodes are being repurposed. They will always return a unique memory
 184 address of the PMC. Uses of get_addr and set_addr that would set label values
 185 for Sub, Exception, and related PMC types will instead be handled by
 186 get_label and set_label.
 187
 188 =item get_results opcode order and features [eligible in 2.1]
 189
 190 get_results no longer used to fetch exception object.
 191
 192 L<https://trac.parrot.org/parrot/ticket/1406>
 193
 194 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
 195
 196 Ability to get the string name of the current GC core from the interpinfo_s_i.
 197 See r43900 and r43904 for details.
 198
 199 L<https://trac.parrot.org/parrot/ticket/1581>
 200
 201 =item NCI_FB_CB and NCI_FB_UD in iglobals [experimental]
 202
 203 Hooks allowing a runtime-loadable dynamic frame builder.
 204
 205 L<https://trac.parrot.org/parrot/ticket/1582>
 206
 207 =item loadlib_p_s_p [experimental]
 208
 209 Ability to use non-default dynamic loading behaviour.
 210
 211 L<https://trac.parrot.org/parrot/ticket/1583>
 212
 213 =item new_callback_p_p_p_s [eligible in 2.4]
 214
 215 To be replaced with new_callback_p_p_p_p_s.
 216
 217 L<https://trac.parrot.org/parrot/ticket/1548>
 218
 219 =item dlfunc and new_callback signature string format [eligible in 2.4]
 220
 221 These will be changed to allow more flexibility in types.
 222
 223 L<https://trac.parrot.org/parrot/ticket/1565>
 224
 225 =item find_lex [eligible in 2.4]
 226
 227 find_lex will not throw exception for non-existing lexicals.
 228
 229 L<https://trac.parrot.org/parrot/ticket/1207>
 230
 231 =item inplace string updates. [eligible in 2.4]
 232
 233 All "inplace" string update ops are deprecated. E.g. "chopn_s", etc.
 234 Part of COW removal.
 235
 236 L<https://trac.parrot.org/parrot/ticket/1540>
 237
 238 =item find_codepoint [experimental]
 239
 240 Intended to replace the CodeString charname_to_ord method.
 241
 242 L<https://trac.parrot.org/parrot/ticket/1629>
 243
 244 =item All opcodes that modify non-argument registers. [eligible in 2.7]
 245
 246 E.g. "cleari", etc.
 247
 248 L<https://trac.parrot.org/parrot/ticket/1642>
 249
 250 =item exchange [eligible in 2.7]
 251
 252 This op is too low level for Parrot in its current form.
 253
 254 L<https://trac.parrot.org/parrot/ticket/1643>
 255
 256 =item finalize [experimental]
 257
 258 Finalize exception handler, unrolling inner runloops if needed.
 259
 260 L<https://trac.parrot.org/parrot/ticket/1635>
 261
 262 =item logical PMC ops [eligible in 2.7]
 263
 264 These fall out from the logical vtables deprecation.
 265
 266 L<https://trac.parrot.org/parrot/ticket/1655>
 267
 268 =item errorson, errorsoff operations [eligible in 2.10]
 269
 270 The C<.PARROT_ERRORS_GLOBAL_FLAG> flag will be eliminated. It is not used by Parrot.
 271
 272 =back
 273
 274 =head1 Bytecode
 275
 276 =over 4
 277
 278 =item packfile structure [experimental]
 279
 280 L<https://trac.parrot.org/parrot/ticket/451>
 281
 282 =item opcode numbering [experimental]
 283
 284 L<https://trac.parrot.org/parrot/ticket/451>
 285
 286 =item PMC numbering [experimental]
 287
 288 L<https://trac.parrot.org/parrot/ticket/451>
 289
 290 =back
 291
 292 =head1 Debugger
 293
 294 Assigning to registers [experimental]
 295
 296 =head1 PIR syntax
 297
 298 =over 4
 299
 300 =item Assignment syntax with opcodes [eligible in 1.1]
 301
 302 L<https://trac.parrot.org/parrot/ticket/906>
 303
 304 =item continuation-based ExceptionHandlers [eligible in 2.1]
 305
 306 L<https://trac.parrot.org/parrot/ticket/1091>
 307
 308 =item implicit optional named parameters [eligible in 2.1]
 309
 310 L<https://trac.parrot.org/parrot/ticket/1103>
 311
 312 =item :unique_reg flag [eligible in 2.7]
 313
 314 L<https://trac.parrot.org/parrot/ticket/1622>
 315
 316 =item .nci_call [eligible in 2.7]
 317
 318 As of the latest PCC changes, there is nothing special about calling an NCI sub.
 319
 320 L<https://trac.parrot.org/parrot/ticket/1623>
 321
 322 =item .meth_call [eligible in 2.7]
 323
 324 As of the latest PCC changes, this does nothing different from '.call'.
 325
 326 L<https://trac.parrot.org/parrot/ticket/1624>
 327
 328 =item :main Sub behaviour and selection. [eligible in 2.7]
 329
 330 Currently, if no :main sub is found, the first .sub in a file is used as
 331 main. Also, arguments are passed to the main sub regardless of the .param
 332 declarations in that sub.
 333
 334 After this change, if no sub is marked with :main, an exception will be
 335 raised. Multiple :main declarations will be still be allowed, and all but the
 336 first will be ignored.
 337
 338 This change will also force all subs, including :main, to have their
 339 arguments checked - to allow an arbitrary number of arguments, have
 340 this be the only .param declaration in the sub.
 341
 342  .param pmc args :slurpy
 343
 344
 345 L<https://trac.parrot.org/parrot/ticket/1033>
 346 L<https://trac.parrot.org/parrot/ticket/1704>
 347 L<https://trac.parrot.org/parrot/ticket/1705>
 348
 349 =back
 350
 351 =head1 Functions
 352
 353 =over 4
 354
 355 =item mmd_cvt_to_types [eligible in 1.1]
 356
 357 L<https://trac.parrot.org/parrot/ticket/907>
 358
 359 =item C API coding standards cleanup [eligible in 1.1]
 360
 361 All C API functions that aren't currently named according to the
 362 'Parrot_<system>_*' scheme will be renamed. A list of renamed
 363 functions will be kept in the ticket at:
 364
 365 L<https://trac.parrot.org/parrot/ticket/443>
 366
 367 =item PMC Attributes Allocation Functions [experimental]
 368
 369  Parrot_gc_allocate_pmc_attributes
 370  Parrot_gc_free_pmc_attributes
 371
 372 These items and related helper functions are added as experimental support
 373 for L<https://trac.parrot.org/parrot/ticket/1506>
 374
 375 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 376
 377 All STRING modification functions will return a STRING pointer; capture and use
 378 this rather than relying on in-place modification of an existing pointer.
 379
 380 L<https://trac.parrot.org/parrot/ticket/1584>
 381
 382 =item STRING COW [eligible in 2.4]
 383
 384 COW strings are to be removed. All "inplace" string modification
 385 functions and all "inplace" string ops are deprecated.
 386
 387 L<https://trac.parrot.org/parrot/ticket/1540>
 388
 389 =item Parrot_str_unescape_string [experimental]
 390
 391 This function is an experimental addition to enhance and maybe replace
 392 Parrot_str_unescape
 393
 394 L<https://trac.parrot.org/parrot/ticket/1628>
 395
 396 =item Parrot_getpid [experimental]
 397
 398 Get process id, experimental.
 399
 400 L<https://trac.parrot.org/parrot/ticket/1564>
 401
 402 =back
 403
 404 =head1 Compiler tools
 405
 406 =head2 Parrot Grammar Engine (PGE)
 407
 408 =over 4
 409
 410 =item Action methods in rules
 411
 412 Per Synopsis 5, all regexes will have an implied {*} token at the
 413 end which cause invocation of an action method if a C<:action>
 414 object is supplied.
 415
 416 L<https://trac.parrot.org/parrot/ticket/843>
 417
 418 =back
 419
 420 =head2 Parrot Compiler Toolkit
 421
 422 =over 4
 423
 424 =item PCT::HLLCompiler stages [eligible in 1.1]
 425
 426 The interface of various methods for adding, removing, and modifying
 427 the list stages in a PCT::HLLCompiler object is subject to change.
 428 The existing actual stages will remain; only the mechanism for specifying
 429 the order of individual stages is likely to change.
 430
 431 L<https://trac.parrot.org/parrot/ticket/462>
 432
 433 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 434
 435 In order to facilitate using PCT::HLLCompiler with test harnesses,
 436 the C<command_line> method of PCT::HLLCompiler object exits silently
 437 if it detects that it is being run in a sample run from Perl's
 438 Test::Harness.  Currently this detection is done by checking the
 439 second command line argument for "@INC"; future releases may
 440 use a different detection mechanism or eliminate it altogether.
 441
 442 L<https://trac.parrot.org/parrot/ticket/463>
 443
 444 =item PAST::Val node generation [eligible in 1.5]
 445
 446 The PAST::Compiler may generate the code for PAST::Val nodes
 447 (i.e., constants) at the beginning of the block (Parrot sub) instead
 448 of the location where they occur in the PAST tree.
 449
 450 L<https://trac.parrot.org/parrot/ticket/868>
 451
 452 =item Meta-model implementation used by PCT [eligible in 2.7]
 453
 454 PCT is set to switch to a new meta-model implementation for its classes
 455 and objects. This will most likely only affect those who rely on the
 456 interface of what is returned from .HOW, or rely on PCT objects exhibiting
 457 various other peculiarities of the P6object implementation. (Even when that
 458 is the case, the HOW API will not be changing too drastically, so for most
 459 PCT users there should be little to no upheavel.)
 460
 461 =back
 462
 463 =head1 Parrot library
 464
 465 =over 4
 466
 467 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 468
 469 L<https://trac.parrot.org/parrot/ticket/1429>
 470
 471 A way to provide an equivalent of -L and -I parrot command line options
 472 to language that doesn't support it.
 473
 474 =item Protoobject [eligible in 2.7]
 475
 476 Use P6Object instead.
 477
 478 L<http://trac.parrot.org/parrot/ticket/1337>
 479
 480 =item Archive::Tar & Archive::Zip [experimental]
 481
 482 L<https://trac.parrot.org/parrot/ticket/1598>
 483
 484 =item LWP, HTTP::Message, URI & URI::Escape [experimental]
 485
 486 L<http://trac.parrot.org/parrot/ticket/1637>
 487
 488 =item JSON and Config;JSON [eligible in 1.5]
 489
 490 L<https://trac.parrot.org/parrot/ticket/508>
 491
 492 =item Cross-HLL library loading [experimental]
 493
 494 L<https://trac.parrot.org/parrot/ticket/754>
 495
 496 =item OpenGL bindings and libraries [experimental]
 497
 498 L<https://trac.parrot.org/parrot/ticket/852>
 499
 500 =back
 501
 502 =head1 Experimental
 503
 504 =over 4
 505
 506 =item Threads and Parallelism [experimental]
 507
 508 L<https://trac.parrot.org/parrot/ticket/1601>
 509
 510 =back
 511
 512 =head1 Footnotes
 513
 514 =over 4
 515
 516 =item 1
 517
 518 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 519
 520 =item 2
 521
 522 For an item to be considered experimental, it can B<never> have shipped in
 523 a supported release without the C<[experimental]> tag; otherwise, it must be
 524 deprecated normally before removal or incompatible change.
 525
 526 =back
 527
 528 =cut