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 =back
 218
 219 =head1 Compiler tools
 220
 221 =head2 Parrot Grammar Engine (PGE)
 222
 223 =over 4
 224
 225 =item Action methods in rules
 226
 227 Per Synopsis 5, all regexes will have an implied {*} token at the
 228 end which cause invocation of an action method if a C<:action>
 229 object is supplied.
 230
 231 L<https://trac.parrot.org/parrot/ticket/843>
 232
 233 =back
 234
 235 =head2 Parrot Compiler Toolkit
 236
 237 =over 4
 238
 239 =item PCT::HLLCompiler stages [eligible in 1.1]
 240
 241 The interface of various methods for adding, removing, and modifying
 242 the list stages in a PCT::HLLCompiler object is subject to change.
 243 The existing actual stages will remain; only the mechanism for specifying
 244 the order of individual stages is likely to change.
 245
 246 L<https://trac.parrot.org/parrot/ticket/462>
 247
 248 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 249
 250 In order to facilitate using PCT::HLLCompiler with test harnesses,
 251 the C<command_line> method of PCT::HLLCompiler object exits silently
 252 if it detects that it is being run in a sample run from Perl's
 253 Test::Harness.  Currently this detection is done by checking the
 254 second command line argument for "@INC"; future releases may
 255 use a different detection mechanism or eliminate it altogether.
 256
 257 L<https://trac.parrot.org/parrot/ticket/463>
 258
 259 =item PAST::Val node generation [eligible in 1.5]
 260
 261 The PAST::Compiler may generate the code for PAST::Val nodes
 262 (i.e., constants) at the beginning of the block (Parrot sub) instead
 263 of the location where they occur in the PAST tree.
 264
 265 L<https://trac.parrot.org/parrot/ticket/868>
 266
 267 =back
 268
 269 =head1 Compilers
 270
 271 =over 4
 272
 273 =item json [eligible in 2.4]
 274
 275 The json compiler was dupicated into data_json some time ago. If you're
 276 using json, just use data_json instead, it's the same code. See TT #1461.
 277
 278 =item nqp [eligible in 2.4]
 279
 280 Replaced by ext/nqp-rx and parrot-nqp.
 281
 282 L<http://trac.parrot.org/parrot/ticket/1462>
 283
 284 =back
 285
 286 =head1 Parrot library
 287
 288 =over 4
 289
 290 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
 291
 292 L<https://trac.parrot.org/parrot/ticket/1429>
 293
 294 A way to provide an equivalent of -L and -I parrot command line options
 295 to language that doesn't support it.
 296
 297 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 298
 299 L<https://trac.parrot.org/parrot/ticket/508>
 300
 301 =item Cross-HLL library loading [experimental]
 302
 303 L<https://trac.parrot.org/parrot/ticket/754>
 304
 305 =item OpenGL bindings and libraries [experimental]
 306
 307 L<https://trac.parrot.org/parrot/ticket/852>
 308
 309 =back
 310
 311 =head1 Footnotes
 312
 313 =over 4
 314
 315 =item 1
 316
 317 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 318
 319 =item 2
 320
 321 For an item to be considered experimental, it can B<never> have shipped in
 322 a stable release without the C<[experimental]> tag; otherwise, it must be
 323 deprecated normally before removal or incompatible change.
 324
 325 =back
 326
 327 =cut