Author: allison
Date: Wed Jul 26 14:44:40 2006
New Revision: 13593
Modified:
trunk/docs/pdds/clip/pdd01_overview.pod
trunk/docs/pdds/clip/pdd04_datatypes.pod
trunk/docs/pdds/clip/pdd05_opfunc.pod
trunk/docs/pdds/clip/pdd06_pasm.pod
trunk/docs/pdds/clip/pdd09_gc.pod
trunk/docs/pdds/clip/pdd12_assembly.pod
trunk/docs/pdds/clip/pdd14_bignum.pod
trunk/docs/pdds/clip/pdd15_objects.pod
trunk/docs/pdds/clip/pdd16_native_call.pod
trunk/docs/pdds/clip/pdd17_basic_types.pod
trunk/docs/pdds/clip/pdd18_security.pod
Changes in other areas also in this revision:
Modified:
trunk/ (props changed)
Log:
A series of short notes on the PDDs from a one-pass review.
Modified: trunk/docs/pdds/clip/pdd01_overview.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd01_overview.pod (original)
+++ trunk/docs/pdds/clip/pdd01_overview.pod Wed Jul 26 14:44:40 2006
@@ -9,6 +9,8 @@
This PDD provides a high-level overview of the Parrot system.
+{{ NOTE: this needs to be more of an overall architecture plan. }}
+
=head1 DESCRIPTION
=head2 Major components
Modified: trunk/docs/pdds/clip/pdd04_datatypes.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd04_datatypes.pod (original)
+++ trunk/docs/pdds/clip/pdd04_datatypes.pod Wed Jul 26 14:44:40 2006
@@ -9,6 +9,9 @@
This PDD describes Parrot's internal data types.
+{{ NOTE: this is a good overview, but we need more complete
+specifications of the behavior of the datatypes. }}
+
=head1 DESCRIPTION
This PDD details the basic datatypes that the Parrot core knows how to deal
Modified: trunk/docs/pdds/clip/pdd05_opfunc.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd05_opfunc.pod (original)
+++ trunk/docs/pdds/clip/pdd05_opfunc.pod Wed Jul 26 14:44:40 2006
@@ -10,6 +10,9 @@
This PDD specifies how the opcode functions should behave and how they are
called by the Parrot interpreter.
+{{ NOTE: this PDD is only loosely connected to the current state of
+Parrot. }}
+
=head1 DESCRIPTION
The opcode functions are the workhorse of the Parrot engine. They control
Modified: trunk/docs/pdds/clip/pdd06_pasm.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd06_pasm.pod (original)
+++ trunk/docs/pdds/clip/pdd06_pasm.pod Wed Jul 26 14:44:40 2006
@@ -16,6 +16,10 @@
for those people who may need to generate bytecode directly, rather than
indirectly via the perl (or any other) language.
+{{ NOTE: out-of-date and incomplete. It seems that it would be more
+useful as a specification of the format of PASM than as a comprehensive
+listing of all opcodes. }}
+
=head1 IMPLEMENTATION
Parrot opcodes take the format of:
@@ -46,18 +50,18 @@
All assembly opcodes contain only ASCII lowercase letters, digits, and the
underscore.
-Upper case names are reserved for assembler directives.
+Upper case names are reserved for assembler directives. {{ NOTE: no
+longer true. }}
Labels all end with a colon. They may have ASCII letters, numbers, and
underscores in them. Labels that begin with a dollar sign (the only valid spot
in a label a dollar sign can appear) are private to the subroutine they appear
in.
-Namespaces are noted with the NAMESPACE directive. It takes a single parameter,
-the name of the namespace. Multilevel namespaces are supported, and the
-namespaces should be double-colon separated.
+Namespaces are noted with the C<.namespace> directive. It takes a single
parameter,
+the name of the namespace, in the form of a multi-dimensional key.
-Subroutine names are noted with the SUB directive. It takes a single parameter,
+Subroutine names are noted with the C<.sub> directive. It takes a single
parameter,
the name of the subroutine, which is added to the namespace's symbol table. Sub
names may be any valid Unicode alphanumeric character and the underscore.
Modified: trunk/docs/pdds/clip/pdd09_gc.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd09_gc.pod (original)
+++ trunk/docs/pdds/clip/pdd09_gc.pod Wed Jul 26 14:44:40 2006
@@ -35,7 +35,7 @@
Starting from the root set (Parrot registers, stacks, internal structures) all
reachable objects (and objects reachable from these) are marked being alive.
-Ojbects not reached are considered being dead and get collected by a sweep
+Objects not reached are considered dead and get collected by a sweep
through the objects arenas.
=item Copying collection
@@ -102,7 +102,7 @@
Variable-sized memory like string memory gets collected, when the associated
header isn't found to be alive during DOD. While a copying collection could
-basically[1] be done at any time, its inefficient to copy buffers of objects
+basically[1] be done at any time, it's inefficient to copy buffers of objects
that are non yet detected being dead. This implies that before a collection in
the memory pools is run, a DOD run for fixed-sized headers is triggered.
@@ -114,7 +114,7 @@
=head2 General Notes
GC subsystems are rather independent. The goal for Parrot is just to provide
-new object headers in the fasted possible way. How that is achieved can be
+new object headers in the fastest possible way. How that is achieved can be
considered as an implementation detail.
While GC subsystems are independent they may share some code to reduce Parrot
@@ -229,7 +229,7 @@
=item C<DOD_WRITE_BARRIER_KEY(Interp*, PMC *agg, PMC *old, PObj *old_key, PMC
*new, PObj *new_key)>
-Like above. Invoked when a hash key is inserted, possibly replacing and old
+Like above. Invoked when a hash key is inserted, possibly replacing an old
key.
=back
Modified: trunk/docs/pdds/clip/pdd12_assembly.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd12_assembly.pod (original)
+++ trunk/docs/pdds/clip/pdd12_assembly.pod Wed Jul 26 14:44:40 2006
@@ -2,4 +2,8 @@
Placeholder - real PDD will appear after consultation
+{{ NOTE: Plan to reclaim number 12 for the Parrot External C API PDD
+(used for both extending and embedding), since PDD 6 is already Parrot
+Assembly. }}
+
=cut
Modified: trunk/docs/pdds/clip/pdd14_bignum.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd14_bignum.pod (original)
+++ trunk/docs/pdds/clip/pdd14_bignum.pod Wed Jul 26 14:44:40 2006
@@ -7,6 +7,9 @@
=head1 ABSTRACT
+{{ NOTE: needs to be compared to current behavior of bignum library.
+Future directions?}}
+
This document describes the big number library, the functionality it provides
and some internal details of interest to people making use of the library.
Some of the areas in which the big number library meet with the rest of Parrot
Modified: trunk/docs/pdds/clip/pdd15_objects.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd15_objects.pod (original)
+++ trunk/docs/pdds/clip/pdd15_objects.pod Wed Jul 26 14:44:40 2006
@@ -212,6 +212,13 @@
-- the offsets of a class' attributes will change from child class to child
class)
+{{ NOTE: one feature I'd like to have is some way to access a list of
+the object's attributes. The particular use I have in mind is dumping
+the attributes of an object a la Data::Dumper. It abuses the notion
+of 'opaque object', so I could be persuaded it's not a good idea. On the
+other hand, it could be an introspective capability offered by Parrot
+but not directly exposed in the HLLs. }}
+
ParrotClass PMCs also have the "I am a class" flag set on them.
The ParrotObject PMC is an array of meta-information and attributes. The
Modified: trunk/docs/pdds/clip/pdd16_native_call.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd16_native_call.pod (original)
+++ trunk/docs/pdds/clip/pdd16_native_call.pod Wed Jul 26 14:44:40 2006
@@ -126,7 +126,7 @@
=head2 Examples
Most of the function parameters are reasonably self-evident. Some, however,
-merit additional explanation. The
+merit additional explanation. The {{ ??? }}
=head2 Callbacks
Modified: trunk/docs/pdds/clip/pdd17_basic_types.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd17_basic_types.pod (original)
+++ trunk/docs/pdds/clip/pdd17_basic_types.pod Wed Jul 26 14:44:40 2006
@@ -5,6 +5,9 @@
docs/pdds/pdd17_basic_types.pod - Document parrot's basic PMC types
+{{ NOTE: could use a better name to differentiate it from PDD 04
+datatypes. Or perhaps the two should be merged. }}
+
=head1 ABSTRACT
This PDD documents the base Parrot PMC types and their behaviours.
Modified: trunk/docs/pdds/clip/pdd18_security.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd18_security.pod (original)
+++ trunk/docs/pdds/clip/pdd18_security.pod Wed Jul 26 14:44:40 2006
@@ -6,6 +6,9 @@
This PDD describes the safety, security, and quota infrastructure of Parrot.
+{{ NOTE: This PDD is inadequate. We want to provide a much more
+extensive level of sandboxing. }}
+
=head1 DESCRIPTION
There are three basic subsystems in Parrot's security system. They are:
