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