# Copyright: 2005 The Perl Foundation.  All Rights Reserved.
# $Id: ROADMAP 10986 2006-01-08 14:15:28Z leo $

=head1 NAME

ROADMAP - A plan for Parrot

=head1 PURPOSE

As of this writing, there is no one place in which all remaining parrot work is
documented. There are various TODO files, the RT queue, comments in the source
code and the documentation. This document is a first pass at unifying this
information and providing a single point of reference for anyone interested in
the current state of the parrot, whether they are developers looking for items
to work on, or external users looking for an idea of when they can expect a
release.

This document is not meant to contain all the metadata regarding particular
tasks, but merely provide a summary of the tasks.

This document is now becoming a roadmap, because the Architect is deep in a
weeklong mindmeld with the Pumpking and the results are being encoded in this
document, among others.

For a high level overview of parrot milestones, please see:
L<http://www.perlfoundation.org/gc/grants/2005-p6-proposal.html>

=head1 CURRENT RELEASE (0.4.1)

Parrot 0.4.1 was released on Jan. 8th, 2006. For a list of new and fixed
feature see L<NEWS>.

=head1 OVERVIEW

The remaining tasks are broken down into the following categories, roughly
listed in the order through which a task might progress.

=head2 METADATA

Each task has certain metadata associated with it which must be tracked.
Eventually all metadata should be stored in RT at L<https://rt.perl.org/rt3/>

=head2 DESIGN

These are pending design decisions which must be made before any code can be
written to implement them. Note - DESIGN I<is> a special kind of documentation
task, but due to the nature of this kind of documentation, it deserves to be
broken out into its own category.

=head2 TODO

Any item, whether visible to parrot users or hidden behind an API, that has
already been designed (but not implemented) belongs here.

=head2 BUGFIX

Any items which have been implemented but don't work as expected.

=head2 PORTABILITY

Any items which are specific to a particular platform or require special
attention for cross-platform compatibility.

=head2 DOCUMENTATION

Any items pertaining to source, API, or user level documentation.

=head2 HIGH LEVEL LANGUAGES

Parrot currently ships with several partial language implementations. Any tasks
which are specific to those languages, or affect cross-language compatibility
will be listed here.

=head1 ISSUES

=head2 METADATA

=over 4

=item *

To be included: docs/pmc, docs/resources, docs/*.pod, anything in SVN not in
docs, RT. (That is, quite a bit.)

[[What does this item mean, exactly?  --Chip]]

The intention was to comb through the various sources of things to be done and
collate them in some fashion. At the time of that writing, none of the tasks
documented in those directories were documented in a central area.  Something a
little nicer than grep -r 'XXX', but that would certainly do for a start.
See also L<docs/BROKEN> --Coke

=back

=head2 DOCUMENTATION

=over 4

=item *

Eliminate dead documentation.  Let historians dig through our subversion
history.  We look forward toward successful deployment.

=item *

When docs and code disagree, they must be brought into agreement immediately.
At the I<very> least, appropriately mark docs that are apparently wrong but may
eventually become right, e.g.: "C<[NOTE: this does not currently work.  Why?
--committer]>".

PDDs are not exceptions to this rule!  Fix them when they're wrong.  Delete
them when they're obsolete.  (Never delete docs lightly, though.  Check first
with someone who should know.)

=item *

Document project goals and priorities, based on Chip's talk to APW as found at
L<http://feather.perl6.nl/~chip/Chip_APW.sxi> or
L<http://feather.perl6.nl/~chip/Chip_APW.pdf>.

=item *

L<memory_internals.pod> has a question about whether or not string reuse is
limited to a single user or multiple users.

=back

=head2 DESIGN

=over 4

=item *

MMD Roundup 2, from the mailing list:

L<http://xrl.us/gvfw> (Link to groups-beta.google.com)

Section 1 of that email needs a decision from the Architect.

=item *

Variable-length register frames are an approved feature, but the design still
needs fleshing out.  Then there are the minor details of documentation and
implementation.  :-,

=item *

Design the standard library to replace all those opcodes that should never have
been opcodes in the first place, e.g. the IO and transcendental math features.

(Note: Whatever tech we use to implement transcendental math should at *worst*
compile to function calls under JIT.  And I'll consider making exceptions for
the transcendantal math if someone can show me why.)

I expect PIR will still let you pretend they're opcodes, though, to avoid
immediate howls of outrage.  (But only silicon-based life forms write PASM, so
we're not worried about that.)

=item *

Do detailed design on new Chip/Leo-agreed-in-principle lexical system.

The key change learns a lesson that Perl 5 only half learned: Lexical values
may be dynamic, but their names and scopes are known at compile time.  It's
just silly to add '$x' to a newly created pad at runtime, over and over and
over, every time the same scope is entered.  Silly.

So the names and scopes will be static data attached to the subroutine, while
the data will be in dynamically created pad entries.

Think of a pseudohash: the static data are like the index hash, which can be
shared and immutable; the storage slots are like the rest of the array, which
can be mutable even when the index hash isn't.

=item *

Finish event and IO specification.

=item *

Finish specification of return continuation and sub being called slots in
interpreter, with introspection

=item *

Spec out bytecode metadata system and introspection/modification system

=item *

Specify what we need to serialize continuations

=item *

Final namespace spec.

=item *

Solidify design for Truly Evil speed hack for fast regex/string matching

=item *

Describe the behavior of init_pmc_props. L<PDD02>

=item *

Describe the behavior of the serialization functions. (freeze, thaw,
thawfinish, visit). L<PDD02>

=item *

Describe the behavior of C<share>. L<PDD02>

=item *

Describe the components of a C<struct PMC_EXT>. L<PDD04>

=item *

Define what bits of the Parrot internals should be exposed as part of the
Parrot API for extension writers.

=back

=head2 TODO

=over 4

=item *

 requester: leo

Ok. In the long run I expect a multi-stage config system. First is to get
miniparrot built and running, then Parrot core. Extensions like gdbm could be
configured at that point or even in a third step.

=item *

IO: Add IO tables, right now IO's just float around.

=item *

Finish PMC for IO object

=item *

IO's "stdio" layer: buffering, seek/random access, shared streams, thread safe

=item *

Copy-on-write IO stacks

=item *

Make IO layer cache the vtable calls to the next layer.

=item *

IO Filters

=item *

IO mmap support

=item *

Bottom level socket/pipe/process support in API

=item *

UTF layers (or should we not bother and do as a filter?)

=item *

Sample programs and test suite

=item *

AIO - On many platforms we must fake async IO, are we doing a background
thread/interp or an inline event queue function that is called every N ops?

=item *

Get digest (probably SHA1) added to bytecode segments

=item *

Speed up the OrderedHash implementation

=item *

Rearchitect internals for the string specifications.

=item *

To PerlClass or not to PerlClass, that is the question. The class hierarchy
should be reworked (e.g. Boolean->PerlInt->Scalar).

=item *

Configuration - missing tests for processor features

=item *

Configuration - duplication, e.g. nvsize/numvalsize

=item *

Tests - ~1/3 of opcodes are uncovered by tests

=item *

IO - Async core isn't there yet, even though it is rumoured to be.

=item *

Overflow detection/promotion to bigint/float types.

=item *

Create C<opcode_process.pl>. L<PDD05>

=item *

Fill in the remaining functions from the EDA, verify that the test suite still
passes, integrate the library into the rest of Parrot, provide PMC types and
suitable opcodes.  Conversion to and from Parrot strings, conversion to and
from floating point types, sprintf output of bignumbers. L<PDD14>

[[What's an EDA? --Coke]]

=item *

Implement the Parrot equivalent of Perl 5's C<$0>, based on recent (January
2005) mailing list activity.

=item *

C<load_bytecode> does not search the library path to load the file.
L<ops/core.ops>

=item *

The debugger needs to clone the interpreter to "allow people to play into the
debugger and then continue the normal execution of the program."
L<ops/debug.ops>

=item *

parrot doesn't catch the exception thrown by the op C<cmod>. L<ops/math.ops>

=back

=head2 BUGFIX

=over 4

=item *

You can add parents to a class with children and objects, and attributes to a
class with children or objects. This is silently allowed and quietly corrupts
the child classes and instantiated objects.

=item *

building miniparrot is broken

=item *

GC issue (copying collector) - immobile strings/buffers get freed during GC.

=item *

Memory leak - PIO subsystem leaks file handles (ParrotIO structures)

=item *

Memory leak - string_to_cstring returns a malloced string, which isn't freed
everywhere

=item *

Memory Leaks - imcc is currently leaking Unit structures and possibly more

=item *

JIT - 64 bit integers on 32 bit machines don't work

=item *

JIT - parrot register inspection is incomplete (P-regs)

=item *

This sequence:

   loop: dec I0
         inc I1       # or add, sub, ...
         if I0, loop

isn't handled correctly on JIT/i386.

=item *

C<Parrot_destroy> currently leaks most of the memory that it is supposed to
free. L<embed.pod>

=back

=head2 PORTABILITY

=over 4

=item *

Portable fcntl() replacement for platforms without it

=item *

See L<PORTABILITY>. Test suite should have no failure on supported platforms.

=item *

Tests - src/tests are not supported on all platforms

=item *

ParrotIO uses integral file descriptors, which may not be portable.
L<ops/io.ops>

=item *

conversion ops for machines without 1/2/4 byte integer data types

=item *

32 bit pointer/64 bit integer and vv.

=item *

dynamic library loading

=back

=head2 HIGH LEVEL LANGUAGES

=over 4

=item *

Items in languages/tcl/TODO must be completed.

=item *

Get python bytecode translator done

=item *

Pass the pie-thon test suite.

=back

=head1 FUTURE

This document should eventually be obsoleted by use of the RT ticketing system,
except to the extent that it documents things that show promise but have not
yet been committed to.  Every task that is actually ready to be done should be
documented in RT, and reports generated based on that information.

=head1 BUGS (in this document)

As for the future development, it has been pointed out that RT is not the best
system for handling such things (though it does have the advantage of being
available). The main point is to have single point of contact to help
volunteers check (and update) the status of issues important to them.

=cut
