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 gziphandle [experimental]
  41
  42 L<https://trac.parrot.org/parrot/ticket/1580>
  43
  44 =item moved to dynpmc [eligible in 1.1]
  45
  46 AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
  47 and Timer.
  48
  49 L<https://trac.parrot.org/parrot/ticket/448>
  50
  51 =item multiple dispatch within core PMCs [eligible in 1.1]
  52
  53 L<https://trac.parrot.org/parrot/ticket/452>
  54
  55 =item Method stdhandle in ParrotInterpreter [experimental]
  56
  57 L<https://trac.parrot.org/parrot/ticket/264>
  58
  59 =item Overriding vtable invoke in PIR objects [experimental]
  60
  61 The VTABLE invoke in object.pmc puts SELF at the start of the
  62 signature call arguments when there is no current object and is
  63 not already here. This allows the usage of $P0() instead of $P0($P0).
  64
  65 L<https://trac.parrot.org/parrot/ticket/103>
  66
  67 =item NCI without signature ("raw" pointers) [eligible in 2.4]
  68
  69 No equivalent functionality is promised. You shouldn't be using this. Here be
  70 segfaults.
  71
  72 L<https://trac.parrot.org/parrot/ticket/1549>
  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 Auto-vivifation of nested aggregated is deprecated.
 109
 110 E.g.
 111
 112   $P0 = new ['Hash']
 113   $S1 = $P0['foo';'bar';'baz']
 114
 115 will not auto-vivify nested hashes and return PMCNULL early.
 116
 117 L<https://trac.parrot.org/parrot/ticket/1561>
 118
 119 =item PMC must use manual_attrs or auto_attrs flag [eligible in 2.4]
 120
 121 PMCs must no longer use default value for manual/auto attribute allocation,
 122 manual_attrs or auto_attrs must be specified.
 123
 124 L<http://trac.parrot.org/parrot/ticket/1506>
 125
 126 =back
 127
 128 =head1 Opcodes
 129
 130 =over 4
 131
 132 =item moved to dynop [eligible in 1.1]
 133
 134 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
 135 (the obscure and rarely used parts), sys.ops.
 136
 137 L<https://trac.parrot.org/parrot/ticket/449>
 138
 139 =item get_addr and set_addr [eligible in 1.5]
 140
 141 L<https://trac.parrot.org/parrot/ticket/218>
 142
 143 These opcodes are being repurposed. They will always return a unique memory
 144 address of the PMC. Uses of get_addr and set_addr that would set label values
 145 for Sub, Exception, and related PMC types will instead be handled by
 146 get_label and set_label.
 147
 148 =item sizeof [eligible in 2.4]
 149
 150 This opcode uses the old integer ID for a PMC type; this opcode should be changed
 151 to use the current methods to lookup a PMC or removed entirely.
 152
 153 L<https://trac.parrot.org/parrot/ticket/633>
 154
 155 =item All bitwise ops [eligible in 2.1]
 156
 157 All bitwise ops (all ops containing C<bitwise> in their names) will be provided
 158 by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
 159 equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
 160 etc) have switched to using them.
 161
 162 L<https://trac.parrot.org/parrot/ticket/1260>
 163
 164 =item get_results opcode order and features [eligible in 2.1]
 165
 166 get_results no longer used to fetch exception object.
 167
 168 L<https://trac.parrot.org/parrot/ticket/1406>
 169
 170 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
 171
 172 Ability to get the string name of the current GC core from the interpinfo_s_i.
 173 See r43900 and r43904 for details.
 174
 175 L<https://trac.parrot.org/parrot/ticket/1581>
 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 L<https://trac.parrot.org/parrot/ticket/1582>
 182
 183 =item loadlib_p_s_p [experimental]
 184
 185 Ability to use non-default dynamic loading behaviour.
 186
 187 L<https://trac.parrot.org/parrot/ticket/1583>
 188
 189 =item pushaction, pushmark, popmark [eligible in 2.4]
 190
 191 L<https://trac.parrot.org/parrot/ticket/876>
 192
 193 =item new_callback_p_p_p_s [eligible in 2.4]
 194
 195 To be replaced with new_callback_p_p_p_p_s.
 196
 197 L<https://trac.parrot.org/parrot/ticket/1548>
 198
 199 =item dlfunc and new_callback signature string format [eligible in 2.4]
 200
 201 These will be changed to allow more flexibility in types.
 202
 203 L<https://trac.parrot.org/parrot/ticket/1565>
 204
 205 =item find_lex [eligible in 2.4]
 206
 207 find_lex will not throw exception for non-existing lexicals.
 208
 209 L<https://trac.parrot.org/parrot/ticket/1207>
 210
 211 =item substr_s_i_i_s [eligible in 2.4]
 212
 213 This op will be replaced with replace_s_s_i_i_s op to clearly indicate
 214 semantic. Part of COW removal.
 215
 216 L<https://trac.parrot.org/parrot/ticket/1540>
 217
 218 =item substr_s_s_i_i_s [eligible in 2.4]
 219
 220 This op is deprecated. Use replace_s_s_i_i_s or substr_s_s_i_i (or both)
 221 instead. Part of COW removal.
 222
 223 L<https://trac.parrot.org/parrot/ticket/1540>
 224
 225 =item inplace string updates. [eligible in 2.4]
 226
 227 All "inplace" string update ops are deprecated. E.g. "chopn_s", etc.
 228 Part of COW removal.
 229
 230 L<https://trac.parrot.org/parrot/ticket/1540>
 231
 232 =back
 233
 234 =head1 Bytecode
 235
 236 =over 4
 237
 238 =item packfile structure [experimental]
 239
 240 L<https://trac.parrot.org/parrot/ticket/451>
 241
 242 =item opcode numbering [experimental]
 243
 244 L<https://trac.parrot.org/parrot/ticket/451>
 245
 246 =item PMC numbering [experimental]
 247
 248 L<https://trac.parrot.org/parrot/ticket/451>
 249
 250 =back
 251
 252 =head1 Debugger
 253
 254 Assigning to registers [experimental]
 255
 256 =head1 PIR syntax
 257
 258 =over 4
 259
 260 =item Assignment syntax with opcodes [eligible in 1.1]
 261
 262 L<https://trac.parrot.org/parrot/ticket/906>
 263
 264 =item continuation-based ExceptionHandlers [eligible in 2.1]
 265
 266 L<https://trac.parrot.org/parrot/ticket/1091>
 267
 268 =item implicit optional named parameters [eligible in 2.1]
 269
 270 L<https://trac.parrot.org/parrot/ticket/1103>
 271
 272 =back
 273
 274 =head1 Functions
 275
 276 =over 4
 277
 278 =item mmd_cvt_to_types [eligible in 1.1]
 279
 280 L<https://trac.parrot.org/parrot/ticket/907>
 281
 282 =item C API coding standards cleanup [eligible in 1.1]
 283
 284 All C API functions that aren't currently named according to the
 285 'Parrot_<system>_*' scheme will be renamed. A list of renamed
 286 functions will be kept in the ticket at:
 287
 288 L<https://trac.parrot.org/parrot/ticket/443>
 289
 290 =item PMC Attributes Allocation Functions [experimental]
 291
 292  Parrot_gc_allocate_pmc_attributes
 293  Parrot_gc_free_pmc_attributes
 294
 295 These items and related helper functions are added as experimental support
 296 for L<https://trac.parrot.org/parrot/ticket/1506>
 297
 298 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 299
 300 All STRING modification functions will return a STRING pointer; capture and use
 301 this rather than relying on in-place modification of an existing pointer.
 302
 303 L<https://trac.parrot.org/parrot/ticket/1584>
 304
 305 =item STRING_is_null function [eligible in 2.4]
 306
 307 renamed to Parrot_str_is_null
 308
 309 L<https://trac.parrot.org/parrot/ticket/1585>
 310
 311 =item Parrot_string_* [eligible in 2.4]
 312
 313 rename Parrot_string_cstring to Parrot_str_cstring
 314
 315 L<https://trac.parrot.org/parrot/ticket/1586>
 316
 317 =item STRING COW [eligible in 2.4]
 318
 319 COW strings are to be removed. All "inplace" string modification
 320 functions and all "inplace" string ops are deprecated.
 321
 322 L<https://trac.parrot.org/parrot/ticket/1540>
 323
 324 =item Parrot_PMC_* in src/extend.c [eligible in 2.4]
 325
 326 These are duplicates of functions in src/extend_vtable.c. Exceptions:
 327
 328   Parrot_PMC_new
 329   Parrot_PMC_typenum
 330   Parrot_PMC_null
 331   Parrot_PMC_set_vtable
 332   Parrot_PMC_newclass
 333
 334 L<https://trac.parrot.org/parrot/ticket/1587>
 335
 336 =item Parrot_VTABLE, Parrot_get_vtable, Parrot_PMC_set_vtable [eligible in 2.4]
 337
 338 These do not expose any functionality that should be available to code outside
 339 of parrot core.
 340
 341 These might get revived in some form to allow for creating new types and adding
 342 vtable-overrides, if that functionality becomes desired.
 343
 344 L<https://trac.parrot.org/parrot/ticket/1588>
 345
 346 =back
 347
 348 =head1 Compiler tools
 349
 350 =head2 Parrot Grammar Engine (PGE)
 351
 352 =over 4
 353
 354 =item Action methods in rules
 355
 356 Per Synopsis 5, all regexes will have an implied {*} token at the
 357 end which cause invocation of an action method if a C<:action>
 358 object is supplied.
 359
 360 L<https://trac.parrot.org/parrot/ticket/843>
 361
 362 =back
 363
 364 =head2 Parrot Compiler Toolkit
 365
 366 =over 4
 367
 368 =item PCT::HLLCompiler stages [eligible in 1.1]
 369
 370 The interface of various methods for adding, removing, and modifying
 371 the list stages in a PCT::HLLCompiler object is subject to change.
 372 The existing actual stages will remain; only the mechanism for specifying
 373 the order of individual stages is likely to change.
 374
 375 L<https://trac.parrot.org/parrot/ticket/462>
 376
 377 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 378
 379 In order to facilitate using PCT::HLLCompiler with test harnesses,
 380 the C<command_line> method of PCT::HLLCompiler object exits silently
 381 if it detects that it is being run in a sample run from Perl's
 382 Test::Harness.  Currently this detection is done by checking the
 383 second command line argument for "@INC"; future releases may
 384 use a different detection mechanism or eliminate it altogether.
 385
 386 L<https://trac.parrot.org/parrot/ticket/463>
 387
 388 =item PAST::Val node generation [eligible in 1.5]
 389
 390 The PAST::Compiler may generate the code for PAST::Val nodes
 391 (i.e., constants) at the beginning of the block (Parrot sub) instead
 392 of the location where they occur in the PAST tree.
 393
 394 L<https://trac.parrot.org/parrot/ticket/868>
 395
 396 =back
 397
 398 =head1 Parrot library
 399
 400 =over 4
 401
 402 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 403
 404 L<https://trac.parrot.org/parrot/ticket/1429>
 405
 406 A way to provide an equivalent of -L and -I parrot command line options
 407 to language that doesn't support it.
 408
 409 =item JSON, and Config;JSON [eligible in 1.5]
 410
 411 L<https://trac.parrot.org/parrot/ticket/508>
 412
 413 =item Cross-HLL library loading [experimental]
 414
 415 L<https://trac.parrot.org/parrot/ticket/754>
 416
 417 =item OpenGL bindings and libraries [experimental]
 418
 419 L<https://trac.parrot.org/parrot/ticket/852>
 420
 421 =back
 422
 423 =head1 Footnotes
 424
 425 =over 4
 426
 427 =item 1
 428
 429 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 430
 431 =item 2
 432
 433 For an item to be considered experimental, it can B<never> have shipped in
 434 a supported release without the C<[experimental]> tag; otherwise, it must be
 435 deprecated normally before removal or incompatible change.
 436
 437 =back
 438
 439 =cut