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