[TT# 1592][t] Improve test for open opcode delegation. All tests in the file pass...
[parrot.git] / DEPRECATED.pod
blob11d2e193b88d6d52768e9d6d7656698f7c49bc30
1 # $Id$
3 =head1 Purpose
5 Provide a list of deprecated and experimental items in parrot.
6 All items in this list should have a corresponding Trac ticket[1].
8 =head1 Experimental Status
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]>.
15 =head1 Deprecated Status
17 Please see F<docs/project/support_policy.pod> for the parrot
18 project's policy regarding deprecated features.
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.
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>.
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:
33  .include 'warnings.pasm'
34  warningson .PARROT_WARNINGS_DEPRECATED_FLAG
36 =head1 PMCS
38 =over 4
40 =item gziphandle [experimental]
42 L<https://trac.parrot.org/parrot/ticket/1580>
44 =item moved to dynpmc [eligible in 1.1]
46 AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
47 and Timer.
49 L<https://trac.parrot.org/parrot/ticket/448>
51 =item multiple dispatch within core PMCs [eligible in 1.1]
53 L<https://trac.parrot.org/parrot/ticket/452>
55 =item Method stdhandle in ParrotInterpreter [experimental]
57 L<https://trac.parrot.org/parrot/ticket/264>
59 =item Overriding vtable invoke in PIR objects [experimental]
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).
65 L<https://trac.parrot.org/parrot/ticket/103>
67 =item NCI without signature ("raw" pointers) [eligible in 2.4]
69 No equivalent functionality is promised. You shouldn't be using this. Here be
70 segfaults.
72 L<https://trac.parrot.org/parrot/ticket/1549>
74 =item UnManagedStruct handling nested structure [eligible in 2.4]
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.
81 L<https://trac.parrot.org/parrot/ticket/1551>
83 =item UnManagedStruct initializer structure [eligible in 2.4]
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.
89 L<https://trac.parrot.org/parrot/ticket/1552>
91 =item UnManagedStruct get_integer, set_integer_native [eligible in 2.4]
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.
96 L<https://trac.parrot.org/parrot/ticket/1553>
98 =item ManagedStruct reallocations based on shape changes [eligible in 2.4]
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.
104 L<https://trac.parrot.org/parrot/ticket/1554>
106 =item Auto-vivification of nested aggregates [eligible in 2.4]
108 Auto-vivifation of nested aggregated is deprecated.
110 E.g.
112   $P0 = new ['Hash']
113   $S1 = $P0['foo';'bar';'baz']
115 will not auto-vivify nested hashes and return PMCNULL early.
117 L<https://trac.parrot.org/parrot/ticket/1561>
119 =item PMC must use manual_attrs or auto_attrs flag [eligible in 2.4]
121 PMCs must no longer use default value for manual/auto attribute allocation,
122 manual_attrs or auto_attrs must be specified.
124 L<http://trac.parrot.org/parrot/ticket/1506>
126 =back
128 =head1 Opcodes
130 =over 4
132 =item moved to dynop [eligible in 1.1]
134 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
135 (the obscure and rarely used parts), sys.ops.
137 L<https://trac.parrot.org/parrot/ticket/449>
139 =item get_addr and set_addr [eligible in 1.5]
141 L<https://trac.parrot.org/parrot/ticket/218>
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.
148 =item sizeof [eligible in 2.4]
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.
153 L<https://trac.parrot.org/parrot/ticket/633>
155 =item All bitwise ops [eligible in 2.1]
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.
162 L<https://trac.parrot.org/parrot/ticket/1260>
164 =item get_results opcode order and features [eligible in 2.1]
166 get_results no longer used to fetch exception object.
168 L<https://trac.parrot.org/parrot/ticket/1406>
170 =item GC_SYS_NAME option to interpinfo_s_i [experimental]
172 Ability to get the string name of the current GC core from the interpinfo_s_i.
173 See r43900 and r43904 for details.
175 L<https://trac.parrot.org/parrot/ticket/1581>
177 =item NCI_FB_CB and NCI_FB_UD in iglobals [experimental]
179 Hooks allowing a runtime-loadable dynamic frame builder.
181 L<https://trac.parrot.org/parrot/ticket/1582>
183 =item loadlib_p_s_p [experimental]
185 Ability to use non-default dynamic loading behaviour.
187 L<https://trac.parrot.org/parrot/ticket/1583>
189 =item pushaction, pushmark, popmark [eligible in 2.4]
191 L<https://trac.parrot.org/parrot/ticket/876>
193 =item new_callback_p_p_p_s [eligible in 2.4]
195 To be replaced with new_callback_p_p_p_p_s.
197 L<https://trac.parrot.org/parrot/ticket/1548>
199 =item dlfunc and new_callback signature string format [eligible in 2.4]
201 These will be changed to allow more flexibility in types.
203 L<https://trac.parrot.org/parrot/ticket/1565>
205 =item find_lex [eligible in 2.4]
207 find_lex will not throw exception for non-existing lexicals.
209 L<https://trac.parrot.org/parrot/ticket/1207>
211 =item substr_s_i_i_s [eligible in 2.4]
213 This op will be replaced with replace_s_s_i_i_s op to clearly indicate
214 semantic. Part of COW removal.
216 L<https://trac.parrot.org/parrot/ticket/1540>
218 =item substr_s_s_i_i_s [eligible in 2.4]
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.
223 L<https://trac.parrot.org/parrot/ticket/1540>
225 =item inplace string updates. [eligible in 2.4]
227 All "inplace" string update ops are deprecated. E.g. "chopn_s", etc.
228 Part of COW removal.
230 L<https://trac.parrot.org/parrot/ticket/1540>
232 =back
234 =head1 Bytecode
236 =over 4
238 =item packfile structure [experimental]
240 L<https://trac.parrot.org/parrot/ticket/451>
242 =item opcode numbering [experimental]
244 L<https://trac.parrot.org/parrot/ticket/451>
246 =item PMC numbering [experimental]
248 L<https://trac.parrot.org/parrot/ticket/451>
250 =back
252 =head1 Debugger
254 Assigning to registers [experimental]
256 =head1 PIR syntax
258 =over 4
260 =item Assignment syntax with opcodes [eligible in 1.1]
262 L<https://trac.parrot.org/parrot/ticket/906>
264 =item continuation-based ExceptionHandlers [eligible in 2.1]
266 L<https://trac.parrot.org/parrot/ticket/1091>
268 =item implicit optional named parameters [eligible in 2.1]
270 L<https://trac.parrot.org/parrot/ticket/1103>
272 =back
274 =head1 Functions
276 =over 4
278 =item mmd_cvt_to_types [eligible in 1.1]
280 L<https://trac.parrot.org/parrot/ticket/907>
282 =item C API coding standards cleanup [eligible in 1.1]
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:
288 L<https://trac.parrot.org/parrot/ticket/443>
290 =item PMC Attributes Allocation Functions [experimental]
292  Parrot_gc_allocate_pmc_attributes
293  Parrot_gc_free_pmc_attributes
295 These items and related helper functions are added as experimental support
296 for L<https://trac.parrot.org/parrot/ticket/1506>
298 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
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.
303 L<https://trac.parrot.org/parrot/ticket/1584>
305 =item STRING_is_null function [eligible in 2.4]
307 renamed to Parrot_str_is_null
309 L<https://trac.parrot.org/parrot/ticket/1585>
311 =item Parrot_string_* [eligible in 2.4]
313 rename Parrot_string_cstring to Parrot_str_cstring
315 L<https://trac.parrot.org/parrot/ticket/1586>
317 =item STRING COW [eligible in 2.4]
319 COW strings are to be removed. All "inplace" string modification
320 functions and all "inplace" string ops are deprecated.
322 L<https://trac.parrot.org/parrot/ticket/1540>
324 =item Parrot_PMC_* in src/extend.c [eligible in 2.4]
326 These are duplicates of functions in src/extend_vtable.c. Exceptions:
328   Parrot_PMC_new
329   Parrot_PMC_typenum
330   Parrot_PMC_null
331   Parrot_PMC_set_vtable
332   Parrot_PMC_newclass
334 L<https://trac.parrot.org/parrot/ticket/1587>
336 =item Parrot_VTABLE, Parrot_get_vtable, Parrot_PMC_set_vtable [eligible in 2.4]
338 These do not expose any functionality that should be available to code outside
339 of parrot core.
341 These might get revived in some form to allow for creating new types and adding
342 vtable-overrides, if that functionality becomes desired.
344 L<https://trac.parrot.org/parrot/ticket/1588>
346 =back
348 =head1 Compiler tools
350 =head2 Parrot Grammar Engine (PGE)
352 =over 4
354 =item Action methods in rules
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.
360 L<https://trac.parrot.org/parrot/ticket/843>
362 =back
364 =head2 Parrot Compiler Toolkit
366 =over 4
368 =item PCT::HLLCompiler stages [eligible in 1.1]
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.
375 L<https://trac.parrot.org/parrot/ticket/462>
377 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
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.
386 L<https://trac.parrot.org/parrot/ticket/463>
388 =item PAST::Val node generation [eligible in 1.5]
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.
394 L<https://trac.parrot.org/parrot/ticket/868>
396 =back
398 =head1 Parrot library
400 =over 4
402 =item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]
404 L<https://trac.parrot.org/parrot/ticket/1429>
406 A way to provide an equivalent of -L and -I parrot command line options
407 to language that doesn't support it.
409 =item JSON, and Config;JSON [eligible in 1.5]
411 L<https://trac.parrot.org/parrot/ticket/508>
413 =item Cross-HLL library loading [experimental]
415 L<https://trac.parrot.org/parrot/ticket/754>
417 =item OpenGL bindings and libraries [experimental]
419 L<https://trac.parrot.org/parrot/ticket/852>
421 =back
423 =head1 Footnotes
425 =over 4
427 =item 1
429 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
431 =item 2
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.
437 =back
439 =cut