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 stable, even though they may
  11 have shipped in a stable 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 moved to dynpmc [eligible in 1.1]
  41
  42 AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
  43 and Timer.
  44
  45 L<https://trac.parrot.org/parrot/ticket/448>
  46
  47 =item multiple dispatch within core PMCs [eligible in 1.1]
  48
  49 L<https://trac.parrot.org/parrot/ticket/452>
  50
  51 =item Method stdhandle in ParrotInterpreter [experimental]
  52
  53 L<https://trac.parrot.org/parrot/ticket/264>
  54
  55 =item Overriding vtable invoke in PIR objects [experimental]
  56
  57 The VTABLE invoke in object.pmc puts SELF at the start of the
  58 signature call arguments when there is no current object and is
  59 not already here. This allows the usage of $P0() instead of $P0($P0).
  60
  61 L<https://trac.parrot.org/parrot/ticket/103>
  62
  63 =item CPointer PMC [eligible in 2.1]
  64
  65 And all uses in the Parrot calling conventions.
  66
  67 L<https://trac.parrot.org/parrot/ticket/1407>
  68
  69 =item Digest dynpmcs [eligible in 2.4]
  70
  71 The digest dynpmcs are, since the posting of this notice, available on
  72 http://gitorious.org/digest-dynpmcs and will no longer be distributed
  73 with parrot after 2.3.
  74
  75 L<https://trac.parrot.org/parrot/ticket/1467>
  76
  77 =item gdbmhash dynpmc [eligible in 2.4]
  78
  79 The gdbmhash dynpmc is, since the posting of this notice, available on
  80 http://gitorious.org/dbm-dynpmcs and will no longer be distributed
  81 with parrot after 2.3.
  82
  83 L<https://trac.parrot.org/parrot/ticket/1469>
  84
  85 =back
  86
  87 =head1 Opcodes
  88
  89 =over 4
  90
  91 =item moved to dynop [eligible in 1.1]
  92
  93 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
  94 (the obscure and rarely used parts), sys.ops.
  95
  96 L<https://trac.parrot.org/parrot/ticket/449>
  97
  98 =item get_addr and set_addr [eligible in 1.5]
  99
 100 L<https://trac.parrot.org/parrot/ticket/218>
 101
 102 These opcodes are being repurposed. They will always return a unique memory
 103 address of the PMC. Uses of get_addr and set_addr that would set label values
 104 for Sub, Exception, and related PMC types will instead be handled by
 105 get_label and set_label.
 106
 107 =item sizeof [eligible in 2.4]
 108
 109 This opcode uses the old integer ID for a PMC type; this opcode should be changed
 110 to use the current methods to lookup a PMC or removed entirely.
 111
 112 L<https://trac.parrot.org/parrot/ticket/633>
 113
 114 =item All bitwise ops [eligible in 2.1]
 115
 116 All bitwise ops (all ops containing C<bitwise> in their names) will be provided
 117 by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
 118 equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
 119 etc) have switched to using them.
 120
 121 L<https://trac.parrot.org/parrot/ticket/1260>
 122
 123 =item get_results opcode order and features [eligible in 2.1]
 124
 125 Move get_results to follow invoke.
 126
 127 L<https://trac.parrot.org/parrot/ticket/1405>
 128
 129 get_results no longer used to fetch exception object.
 130
 131 L<https://trac.parrot.org/parrot/ticket/1406>
 132
 133 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
 134
 135 Ability to get the string name of the current GC core from the interpinfo_s_i.
 136 See r43900 and r43904 for details.
 137
 138 =back
 139
 140 =head1 Bytecode
 141
 142 =over 4
 143
 144 =item packfile structure [experimental]
 145
 146 L<https://trac.parrot.org/parrot/ticket/451>
 147
 148 =item opcode numbering [experimental]
 149
 150 L<https://trac.parrot.org/parrot/ticket/451>
 151
 152 =item PMC numbering [experimental]
 153
 154 L<https://trac.parrot.org/parrot/ticket/451>
 155
 156 =back
 157
 158 =head1 Debugger
 159
 160 Assigning to registers [experimental]
 161
 162 =head1 PIR syntax
 163
 164 =over 4
 165
 166 =item Assignment syntax with opcodes [eligible in 1.1]
 167
 168 L<https://trac.parrot.org/parrot/ticket/906>
 169
 170 =item continuation-based ExceptionHandlers [eligible in 2.1]
 171
 172 L<https://trac.parrot.org/parrot/ticket/1091>
 173
 174 =item implicit optional named parameters [eligible in 2.1]
 175
 176 L<https://trac.parrot.org/parrot/ticket/1103>
 177
 178 =back
 179
 180 =head1 Functions
 181
 182 =over 4
 183
 184 =item mmd_cvt_to_types [eligible in 1.1]
 185
 186 L<https://trac.parrot.org/parrot/ticket/907>
 187
 188 =item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]
 189
 190 Subs marked with C<:vtable> or C<:method> flags are no longer given a
 191 namespace entry by default.  Use the C<:nsentry> flag to cause this
 192 to happen.
 193
 194 L<https://trac.parrot.org/parrot/ticket/389>
 195
 196 =item C API coding standards cleanup [eligible in 1.1]
 197
 198 All C API functions that aren't currently named according to the
 199 'Parrot_<system>_*' scheme will be renamed. A list of renamed
 200 functions will be kept in the ticket at:
 201
 202 L<https://trac.parrot.org/parrot/ticket/443>
 203
 204 =item PMC Attributes Allocation Functions [experimental]
 205
 206  Parrot_gc_allocate_pmc_attributes
 207  Parrot_gc_free_pmc_attributes
 208
 209 These items and related helper functions are added as experimental support
 210 for L<https://trac.parrot.org/parrot/ticket/895>
 211
 212 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 213
 214 All STRING modification functions will return a STRING pointer; capture and use
 215 this rather than relying on in-place modification of an existing pointer.
 216
 217 =item STRING_is_null function [eligible in 2.4]
 218
 219 renamed to Parrot_str_is_null
 220
 221 =item Parrot_string_* [eligible in 2.4]
 222
 223 rename Parrot_string_cstring to Parrot_str_cstring
 224
 225 =item STRING functions which don't have Parrot_str_ prefix
 226
 227 The string subsytem is gradually getting an overhaul.
 228
 229 =back
 230
 231 =head1 Compiler tools
 232
 233 =head2 Parrot Grammar Engine (PGE)
 234
 235 =over 4
 236
 237 =item Action methods in rules
 238
 239 Per Synopsis 5, all regexes will have an implied {*} token at the
 240 end which cause invocation of an action method if a C<:action>
 241 object is supplied.
 242
 243 L<https://trac.parrot.org/parrot/ticket/843>
 244
 245 =back
 246
 247 =head2 Parrot Compiler Toolkit
 248
 249 =over 4
 250
 251 =item PCT::HLLCompiler stages [eligible in 1.1]
 252
 253 The interface of various methods for adding, removing, and modifying
 254 the list stages in a PCT::HLLCompiler object is subject to change.
 255 The existing actual stages will remain; only the mechanism for specifying
 256 the order of individual stages is likely to change.
 257
 258 L<https://trac.parrot.org/parrot/ticket/462>
 259
 260 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 261
 262 In order to facilitate using PCT::HLLCompiler with test harnesses,
 263 the C<command_line> method of PCT::HLLCompiler object exits silently
 264 if it detects that it is being run in a sample run from Perl's
 265 Test::Harness.  Currently this detection is done by checking the
 266 second command line argument for "@INC"; future releases may
 267 use a different detection mechanism or eliminate it altogether.
 268
 269 L<https://trac.parrot.org/parrot/ticket/463>
 270
 271 =item PAST::Val node generation [eligible in 1.5]
 272
 273 The PAST::Compiler may generate the code for PAST::Val nodes
 274 (i.e., constants) at the beginning of the block (Parrot sub) instead
 275 of the location where they occur in the PAST tree.
 276
 277 L<https://trac.parrot.org/parrot/ticket/868>
 278
 279 =back
 280
 281 =head1 Compilers
 282
 283 =over 4
 284
 285 =item json [eligible in 2.4]
 286
 287 The json compiler was dupicated into data_json some time ago. If you're
 288 using json, just use data_json instead, it's the same code. See TT #1461.
 289
 290 =item nqp [eligible in 2.4]
 291
 292 Replaced by ext/nqp-rx and parrot-nqp.
 293
 294 L<http://trac.parrot.org/parrot/ticket/1462>
 295
 296 =back
 297
 298 =head1 Parrot library
 299
 300 =over 4
 301
 302 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 303
 304 L<https://trac.parrot.org/parrot/ticket/1429>
 305
 306 A way to provide an equivalent of -L and -I parrot command line options
 307 to language that doesn't support it.
 308
 309 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 310
 311 L<https://trac.parrot.org/parrot/ticket/508>
 312
 313 =item Cross-HLL library loading [experimental]
 314
 315 L<https://trac.parrot.org/parrot/ticket/754>
 316
 317 =item OpenGL bindings and libraries [experimental]
 318
 319 L<https://trac.parrot.org/parrot/ticket/852>
 320
 321 =back
 322
 323 =head1 Footnotes
 324
 325 =over 4
 326
 327 =item 1
 328
 329 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 330
 331 =item 2
 332
 333 For an item to be considered experimental, it can B<never> have shipped in
 334 a stable release without the C<[experimental]> tag; otherwise, it must be
 335 deprecated normally before removal or incompatible change.
 336
 337 =back
 338
 339 =cut