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 Whenever deprecated items are removed, information
  26 regarding how to cope with the removal should be added to
  27 L<https://trac.parrot.org/parrot/wiki/Deprecation>.
  28
  29 When running parrot, you can receive warnings about deprecated opcodes.
  30 Either run parrot with the C<-w> option to enable all warnings, or
  31 specifically by including this C<PIR> code:
  32
  33  .include 'warnings.pasm'
  34  warningson .PARROT_WARNINGS_DEPRECATED_FLAG
  35
  36 =head1 PMCS
  37
  38 =over 4
  39
  40 =item RetContinuation [eligible in 2.4]
  41
  42 In future, just use Continuation.
  43
  44 L<https://trac.parrot.org/parrot/ticket/1427>
  45
  46 =item moved to dynpmc [eligible in 1.1]
  47
  48 AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
  49 and Timer.
  50
  51 L<https://trac.parrot.org/parrot/ticket/448>
  52
  53 =item multiple dispatch within core PMCs [eligible in 1.1]
  54
  55 L<https://trac.parrot.org/parrot/ticket/452>
  56
  57 =item Method stdhandle in ParrotInterpreter [experimental]
  58
  59 L<https://trac.parrot.org/parrot/ticket/264>
  60
  61 =item Overriding vtable invoke in PIR objects [experimental]
  62
  63 The VTABLE invoke in object.pmc puts SELF at the start of the
  64 signature call arguments when there is no current object and is
  65 not already here. This allows the usage of $P0() instead of $P0($P0).
  66
  67 L<https://trac.parrot.org/parrot/ticket/103>
  68
  69 =item NCI without signature ("raw" pointers) [eligible in 2.4]
  70
  71 No equivalent functionality is promised. You shouldn't be using this. Here be
  72 segfaults.
  73
  74 L<https://trac.parrot.org/parrot/ticket/1549>
  75
  76 =item UnManagedStruct handling nested structure [eligible in 2.4]
  77
  78 UnManagedStruct will be simplified to only support flat structures. This means
  79 that elements which themselves have structure - struct pointers and function
  80 pointers will be stored as C<void *> and C<void (*)(void)> respectively. To use
  81 these, they will need to be cast to the appropriate signature on access.
  82
  83 L<https://trac.parrot.org/parrot/ticket/1551>
  84
  85 =item UnManagedStruct initializer structure [eligible in 2.4]
  86
  87 The initializer structure will cease to be an array of triples. In stead, an
  88 array of flags (no counts or offsets), or a string representation of the same
  89 information may be used.
  90
  91 L<https://trac.parrot.org/parrot/ticket/1552>
  92
  93 =item UnManagedStruct get_integer, set_integer_native [eligible in 2.4]
  94
  95 These will no longer refer to the byte length of the buffer, but to the number
  96 of times the struct is repeated; emulating an array of structs.
  97
  98 L<https://trac.parrot.org/parrot/ticket/1553>
  99
 100 =item ManagedStruct reallocations based on shape changes [eligible in 2.4]
 101
 102 Since shape changes may simply be used for re-interpreting data, and may also
 103 occur in several steps, re-allocating after any one shape change may be
 104 undesirable. In stead, an explicit allocate/reallocate method will be provided.
 105
 106 L<https://trac.parrot.org/parrot/ticket/1554>
 107
 108 =item Auto-vivification of nested aggregates [eligible in 2.4]
 109
 110 Auto-vivifation of nested aggregated is deprecated.
 111
 112 E.g.
 113
 114   $P0 = new ['Hash']
 115   $S1 = $P0['foo';'bar';'baz']
 116
 117 will not auto-vivify nested hashes and return PMCNULL early.
 118
 119 L<https://trac.parrot.org/parrot/ticket/1561>
 120
 121 =item PMC must use manual_attrs or auto_attrs flag [eligible in 2.4]
 122
 123 PMCs must no longer use default value for manual/auto attribute allocation,
 124 manual_attrs or auto_attrs must be specified.
 125
 126 L<http://trac.parrot.org/parrot/ticket/1506>
 127
 128 =back
 129
 130 =head1 Opcodes
 131
 132 =over 4
 133
 134 =item moved to dynop [eligible in 1.1]
 135
 136 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
 137 (the obscure and rarely used parts), sys.ops.
 138
 139 L<https://trac.parrot.org/parrot/ticket/449>
 140
 141 =item get_addr and set_addr [eligible in 1.5]
 142
 143 L<https://trac.parrot.org/parrot/ticket/218>
 144
 145 These opcodes are being repurposed. They will always return a unique memory
 146 address of the PMC. Uses of get_addr and set_addr that would set label values
 147 for Sub, Exception, and related PMC types will instead be handled by
 148 get_label and set_label.
 149
 150 =item sizeof [eligible in 2.4]
 151
 152 This opcode uses the old integer ID for a PMC type; this opcode should be changed
 153 to use the current methods to lookup a PMC or removed entirely.
 154
 155 L<https://trac.parrot.org/parrot/ticket/633>
 156
 157 =item All bitwise ops [eligible in 2.1]
 158
 159 All bitwise ops (all ops containing C<bitwise> in their names) will be provided
 160 by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
 161 equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
 162 etc) have switched to using them.
 163
 164 L<https://trac.parrot.org/parrot/ticket/1260>
 165
 166 =item get_results opcode order and features [eligible in 2.1]
 167
 168 get_results no longer used to fetch exception object.
 169
 170 L<https://trac.parrot.org/parrot/ticket/1406>
 171
 172 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
 173
 174 Ability to get the string name of the current GC core from the interpinfo_s_i.
 175 See r43900 and r43904 for details.
 176
 177 =item NCI_FB_CB and NCI_FB_UD in iglobals [experimental]
 178
 179 Hooks allowing a runtime-loadable dynamic frame builder.
 180
 181 =item loadlib_p_s_p [experimental]
 182
 183 Ability to use non-default dynamic loading behaviour.
 184
 185 =item pushaction, pushmark, popmark [eligible in 2.4]
 186
 187 L<https://trac.parrot.org/parrot/ticket/876>
 188
 189 =item new_callback_p_p_p_s [eligible in 2.4]
 190
 191 To be replaced with new_callback_p_p_p_p_s.
 192
 193 L<https://trac.parrot.org/parrot/ticket/1548>
 194
 195 =item dlfunc and new_callback signature string format [eligible in 2.4]
 196
 197 These will be changed to allow more flexibility in types.
 198
 199 L<https://trac.parrot.org/parrot/ticket/1565>
 200
 201 =item find_lex [eligible in 2.4]
 202
 203 find_lex will not throw exception for non-existing lexicals.
 204
 205 L<https://trac.parrot.org/parrot/ticket/1207>
 206
 207 =item substr_s_i_i_s [eligible in 2.4]
 208
 209 This op will be replaced with replace_s_s_i_i_s op to clearly indicate
 210 semantic. Part of COW removal.
 211
 212 L<https://trac.parrot.org/parrot/ticket/1540>
 213
 214 =item substr_s_s_i_i_s [eligible in 2.4]
 215
 216 This op is deprecated. Use replace_s_s_i_i_s or substr_s_s_i_i (or both)
 217 instead. Part of COW removal.
 218
 219 L<https://trac.parrot.org/parrot/ticket/1540>
 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 =back
 229
 230 =head1 Runcores
 231
 232 =over 4
 233
 234 =item Unused Runcores [eligible in 2.4]
 235
 236 The following Runcores do not appear to be used.  Accordingly they will
 237 be eligible for removal.
 238
 239 CGoto
 240 CGP
 241 Switch
 242
 243 L<https://trac.parrot.org/parrot/ticket/1563>
 244
 245 =back
 246
 247 =head1 Bytecode
 248
 249 =over 4
 250
 251 =item packfile structure [experimental]
 252
 253 L<https://trac.parrot.org/parrot/ticket/451>
 254
 255 =item opcode numbering [experimental]
 256
 257 L<https://trac.parrot.org/parrot/ticket/451>
 258
 259 =item PMC numbering [experimental]
 260
 261 L<https://trac.parrot.org/parrot/ticket/451>
 262
 263 =back
 264
 265 =head1 Debugger
 266
 267 Assigning to registers [experimental]
 268
 269 =head1 PIR syntax
 270
 271 =over 4
 272
 273 =item Assignment syntax with opcodes [eligible in 1.1]
 274
 275 L<https://trac.parrot.org/parrot/ticket/906>
 276
 277 =item continuation-based ExceptionHandlers [eligible in 2.1]
 278
 279 L<https://trac.parrot.org/parrot/ticket/1091>
 280
 281 =item implicit optional named parameters [eligible in 2.1]
 282
 283 L<https://trac.parrot.org/parrot/ticket/1103>
 284
 285 =back
 286
 287 =head1 Functions
 288
 289 =over 4
 290
 291 =item mmd_cvt_to_types [eligible in 1.1]
 292
 293 L<https://trac.parrot.org/parrot/ticket/907>
 294
 295 =item C API coding standards cleanup [eligible in 1.1]
 296
 297 All C API functions that aren't currently named according to the
 298 'Parrot_<system>_*' scheme will be renamed. A list of renamed
 299 functions will be kept in the ticket at:
 300
 301 L<https://trac.parrot.org/parrot/ticket/443>
 302
 303 =item PMC Attributes Allocation Functions [experimental]
 304
 305  Parrot_gc_allocate_pmc_attributes
 306  Parrot_gc_free_pmc_attributes
 307
 308 These items and related helper functions are added as experimental support
 309 for L<https://trac.parrot.org/parrot/ticket/895>
 310
 311 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 312
 313 All STRING modification functions will return a STRING pointer; capture and use
 314 this rather than relying on in-place modification of an existing pointer.
 315
 316 =item STRING_is_null function [eligible in 2.4]
 317
 318 renamed to Parrot_str_is_null
 319
 320 =item Parrot_string_* [eligible in 2.4]
 321
 322 rename Parrot_string_cstring to Parrot_str_cstring
 323
 324 =item STRING COW [eligible in 2.4]
 325
 326 COW strings are to be removed. All "inplace" string modification
 327 functions and all "inplace" string ops are deprecated.
 328
 329 L<https://trac.parrot.org/parrot/ticket/1540>
 330
 331 =item Parrot_PMC_* in src/extend.c [eligible in 2.4]
 332
 333 These are duplicates of functions in src/extend_vtable.c. Exceptions:
 334
 335   Parrot_PMC_new
 336   Parrot_PMC_typenum
 337   Parrot_PMC_null
 338   Parrot_PMC_set_vtable
 339   Parrot_PMC_newclass
 340
 341 =item Parrot_VTABLE, Parrot_get_vtable, Parrot_PMC_set_vtable [eligible in 2.4]
 342
 343 These do not expose any functionality that should be available to code outside
 344 of parrot core.
 345
 346 These might get revived in some form to allow for creating new types and adding
 347 vtable-overrides, if that functionality becomes desired.
 348
 349 =back
 350
 351 =head1 Compiler tools
 352
 353 =head2 Parrot Grammar Engine (PGE)
 354
 355 =over 4
 356
 357 =item Action methods in rules
 358
 359 Per Synopsis 5, all regexes will have an implied {*} token at the
 360 end which cause invocation of an action method if a C<:action>
 361 object is supplied.
 362
 363 L<https://trac.parrot.org/parrot/ticket/843>
 364
 365 =back
 366
 367 =head2 Parrot Compiler Toolkit
 368
 369 =over 4
 370
 371 =item PCT::HLLCompiler stages [eligible in 1.1]
 372
 373 The interface of various methods for adding, removing, and modifying
 374 the list stages in a PCT::HLLCompiler object is subject to change.
 375 The existing actual stages will remain; only the mechanism for specifying
 376 the order of individual stages is likely to change.
 377
 378 L<https://trac.parrot.org/parrot/ticket/462>
 379
 380 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 381
 382 In order to facilitate using PCT::HLLCompiler with test harnesses,
 383 the C<command_line> method of PCT::HLLCompiler object exits silently
 384 if it detects that it is being run in a sample run from Perl's
 385 Test::Harness.  Currently this detection is done by checking the
 386 second command line argument for "@INC"; future releases may
 387 use a different detection mechanism or eliminate it altogether.
 388
 389 L<https://trac.parrot.org/parrot/ticket/463>
 390
 391 =item PAST::Val node generation [eligible in 1.5]
 392
 393 The PAST::Compiler may generate the code for PAST::Val nodes
 394 (i.e., constants) at the beginning of the block (Parrot sub) instead
 395 of the location where they occur in the PAST tree.
 396
 397 L<https://trac.parrot.org/parrot/ticket/868>
 398
 399 =back
 400
 401 =head1 Compilers
 402
 403 =over 4
 404
 405 =item json [eligible in 2.4]
 406
 407 The json compiler was dupicated into data_json some time ago. If you're
 408 using json, just use data_json instead, it's the same code. See TT #1461.
 409
 410 =item nqp [eligible in 2.4]
 411
 412 Replaced by ext/nqp-rx and parrot-nqp.
 413
 414 L<http://trac.parrot.org/parrot/ticket/1462>
 415
 416 =back
 417
 418 =head1 Parrot library
 419
 420 =over 4
 421
 422 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 423
 424 L<https://trac.parrot.org/parrot/ticket/1429>
 425
 426 A way to provide an equivalent of -L and -I parrot command line options
 427 to language that doesn't support it.
 428
 429 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 430
 431 L<https://trac.parrot.org/parrot/ticket/508>
 432
 433 =item Cross-HLL library loading [experimental]
 434
 435 L<https://trac.parrot.org/parrot/ticket/754>
 436
 437 =item OpenGL bindings and libraries [experimental]
 438
 439 L<https://trac.parrot.org/parrot/ticket/852>
 440
 441 =back
 442
 443 =head1 Footnotes
 444
 445 =over 4
 446
 447 =item 1
 448
 449 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 450
 451 =item 2
 452
 453 For an item to be considered experimental, it can B<never> have shipped in
 454 a supported release without the C<[experimental]> tag; otherwise, it must be
 455 deprecated normally before removal or incompatible change.
 456
 457 =back
 458
 459 =cut