Author: kjs
Date: Sun Dec 28 02:12:50 2008
New Revision: 34472
Modified:
trunk/compilers/pirc/new/pircompunit.c
Log:
[pirc] add and update function documentation.
Modified: trunk/compilers/pirc/new/pircompunit.c
==============================================================================
--- trunk/compilers/pirc/new/pircompunit.c (original)
+++ trunk/compilers/pirc/new/pircompunit.c Sun Dec 28 02:12:50 2008
@@ -49,7 +49,7 @@
=item C<void
-panic(lexer_state * lexer, char * const message)>
+panic(lexer_state * lexer, char const * const message)>
Function to emit a final last cry that something's wrong and exit.
@@ -106,7 +106,7 @@
/*
=item C<void
-set_sub_outer(lexer_state * const lexer, char * const outersub)>
+set_sub_outer(lexer_state * const lexer, char const * const outersub)>
Set the lexically enclosing sub for the current sub.
Thus, set the :outer() argument to the current subroutine.
@@ -124,7 +124,7 @@
/*
=item C<void
-set_sub_vtable(lexer_state * const lexer, char const *vtablename)>
+set_sub_vtable(lexer_state * const lexer, char const * vtablename)>
Set the :vtable() flag argument to the current subroutine. If C<vtablename>
is NULL, the name of the current sub is taken to be the vtable method name.
@@ -159,7 +159,7 @@
/*
=item C<void
-set_sub_subid(lexer_state * const lexer, char * const subid)>
+set_sub_subid(lexer_state * const lexer, char const * const subid)>
Set the name specified in the :subid flag on the sub.
@@ -175,7 +175,7 @@
/*
=item C<void
-set_sub_methodname(lexer_state * const lexer, char * const methodname)>
+set_sub_methodname(lexer_state * const lexer, char const * const methodname)>
Set the :method flag on a sub; if C<methodname> is not NULL, then it contains
the name by which the sub is stored as a method.
@@ -196,7 +196,7 @@
/*
=item C<void
-set_sub_instanceof(lexer_state * const lexer, char * const classname)>
+set_sub_instanceof(lexer_state * const lexer, char const * const classname)>
Set the value of the C<:instanceof> flag on a sub. Note that this flag
is experimental, and not actually used at this point.
@@ -248,7 +248,7 @@
/*
=item C<void
-new_subr(lexer_state * const lexer, char * const subname)>
+new_subr(lexer_state * const lexer, char const * const subname)>
Create a new subroutine node, and set it as the "current"
subroutine, on which all other sub-related operations do
@@ -306,7 +306,7 @@
/*
=item C<void
-set_sub_name(struct lexer_state * const lexer, char const * const subname)>
+set_sub_name(lexer_state * const lexer, char const * const subname)>
Set the current subroutine's name to C<subname>.
@@ -314,7 +314,7 @@
*/
void
-set_sub_name(struct lexer_state * const lexer, char const * const subname) {
+set_sub_name(lexer_state * const lexer, char const * const subname) {
CURRENT_SUB(lexer)->info.subname = subname;
}
@@ -322,7 +322,7 @@
/*
=item C<static instruction *
-new_instruction(char * const opname)>
+new_instruction(lexer_state * const lexer, char const * const opname)>
Create a new instruction node and set C<opname> as the instruction.
@@ -342,7 +342,7 @@
/*
=item C<static void
-new_statement(lexer_state * const lexer)>
+new_statement(lexer_state * const lexer, char const * const opname)>
Constructor for a statement. The newly allocated statement will be inserted
into the current subroutine's statements list.
@@ -551,7 +551,7 @@
/*
=item C<target *
-add_param(lexer_state * const lexer, pir_type type, char * const name)>
+add_param(lexer_state * const lexer, pir_type type, char const * const name)>
Add a parameter of type C<type> and named C<name> to the current
subroutine. The parameter will be declared as a local symbol in the
@@ -600,7 +600,7 @@
/*
=item C<void
-set_param_alias(lexer_state * const lexer, char * const alias)>
+set_param_alias(lexer_state * const lexer, char const * const alias)>
Set the argument of the :named flag for the current target
(parameter). Returns the current target (parameter).
@@ -659,7 +659,7 @@
/*
=item C<argument *
-new_argument(expression * const expr)>
+new_argument(lexer_state * const lexer, expression * const expr)>
Create a new argument node which wraps C<expr>.
@@ -729,7 +729,7 @@
/*
=item C<void
-set_arg_alias(lexer_state * const lexer, char * const alias)>
+set_arg_alias(lexer_state * const lexer, char const * const alias)>
Set the alias specified in C<alias> on the current argument, accessible
through C<lexer>. The alias is the name under which the argument is passed
@@ -752,7 +752,7 @@
/*
=item C<void
-load_library(lexer_state * const lexer, char * const library)>
+load_library(lexer_state * const lexer, char const * const library)>
Load the library indicated by C<library>.
@@ -772,7 +772,7 @@
/*
=item C<void
-set_label(lexer_state * const lexer, char * const label)>
+set_label(lexer_state * const lexer, char const * const label)>
Set the label C<label> on the current instruction.
@@ -1151,6 +1151,8 @@
get_operand_count(lexer_state * const lexer)>
Returns the number of operands of the I<current> instruction.
+This function assumes there is an instruction in place
+(in CURRENT_INSTRUCTION(lexer)).
=cut
@@ -1161,6 +1163,8 @@
unsigned count = 0;
expression *first, *operand;
+ PARROT_ASSERT(CURRENT_INSTRUCTION(lexer));
+
/* if no operands, return 0 */
if (CURRENT_INSTRUCTION(lexer)->operands == NULL)
return 0;
@@ -1220,7 +1224,6 @@
/*
-
=item C<constant *
new_named_const(lexer_state * const lexer, pir_type type, char * const name,
...)>
@@ -1372,7 +1375,8 @@
=item C<expression *
expr_from_target(target *t)>
-convert a target to an expression node
+Wrap a target in an expression node; the expression node is
+returned.
=cut
@@ -1529,7 +1533,7 @@
/*
=item C<void
-set_lex_flag(target *t, char * const name)>
+set_lex_flag(target * const t, char const * const name)>
Set the lexical name C<name> on target C<t>.
@@ -2202,11 +2206,40 @@
new_sub_instr(lexer, PARROT_OP_returncc, "returncc");
}
+/*
+
+=item C<static void
+convert_nci_call(lexer_state * const lexer, invocation * const inv)>
+
+Generate instructions for a function invocation using the Native Call
+Interface (NCI). The sequence of instructions is:
+
+XXX complete this.
+
+ invokecc_p
+
+=cut
+
+*/
static void
convert_nci_call(lexer_state * const lexer, invocation * const inv) {
set_instr(lexer, "invokecc_p");
}
+/*
+
+=item C<static void
+convert_pcc_yield(lexer_state * const lexer, invocation * const inv)>
+
+Generate instructions for a yield statement using the Parrot Calling
Conventions.
+The sequence of instructions is:
+
+ set_returns_pc
+ yield
+
+=cut
+
+*/
static void
convert_pcc_yield(lexer_state * const lexer, invocation * const inv) {
new_sub_instr(lexer, PARROT_OP_set_returns_pc, "set_returns_pc");
@@ -2215,6 +2248,20 @@
new_sub_instr(lexer, PARROT_OP_yield, "yield");
}
+/*
+
+=item C<static void
+convert_pcc_tailcall(lexer_state * const lexer, invocation * const inv)>
+
+Generate instructions for a tailcall using the Parrot Calling Conventions
(PCC).
+The sequence of instructions is:
+
+ set_args_pc
+ tailcall_pc
+
+=cut
+
+*/
static void
convert_pcc_tailcall(lexer_state * const lexer, invocation * const inv) {
new_sub_instr(lexer, PARROT_OP_set_args_pc, "set_args_pc");
@@ -2223,6 +2270,21 @@
new_sub_instr(lexer, PARROT_OP_tailcall_p, "tailcall_pc");
}
+/*
+
+=item C<static void
+convert_pcc_methodcall(lexer_state * const lexer, invocation * const inv)>
+
+Generate instructions for a method call using the Parrot Calling Conventions
(PCC).
+The sequence of instructions is:
+
+ set_args_pc
+ get_results_pc
+ callmethodcc_p_sc
+
+=cut
+
+*/
static void
convert_pcc_methodcall(lexer_state * const lexer, invocation * const inv) {
new_sub_instr(lexer, PARROT_OP_set_args_pc, "set_args_pc");
@@ -2237,6 +2299,20 @@
add_operands(lexer, "%T%E", inv->sub, inv->method);
}
+/*
+
+=item C<static void
+convert_pcc_methodtailcall(lexer_state * const lexer, invocation * const inv)>
+
+Generate instructions for a method tailcall, using the Parrot Calling
Conventions (PCC).
+The sequence of instructions is:
+
+ set_args_pc
+ tailcallmethod_p_p / tailcallmethod_p_sc
+
+=cut
+
+*/
static void
convert_pcc_methodtailcall(lexer_state * const lexer, invocation * const inv) {
new_sub_instr(lexer, PARROT_OP_set_args_pc, "set_args_pc");
@@ -2257,7 +2333,9 @@
=item C<void
convert_inv_to_instr(lexer_state * const lexer, invocation * const inv)>
-Convert an C<invocation> structure into a series of instructions.
+Convert an C<invocation> structure into a series of instructions. This is the
+dispatch function, which calls the appropriate conversion function, based
+on the type of C<inv>.
=cut
@@ -2298,7 +2376,9 @@
=item C<static label *
new_label(lexer_state * const lexer, char const * const labelid, int offset)>
-Constructor for a label operand.
+Constructor for a label struct node. A new C<label> object is created,
+initialized with the label id specified in C<labelid>, and the bytecode
+offset in C<offset>. A pointer to the label node is returned.
=cut
@@ -2337,12 +2417,10 @@
do {
iter = iter->next; /* init pointer to first instruction */
- /* depending on what kind of branching instruction, get the right
operand
- * that contains the label.
+ /* Do a quick global check if any label bits have been set
+ * if no label at all, skip this whole block.
*/
- if (iter->oplabelbits) { /* this is a quick global check if any label
bits have been set
- * if no label at all, skip this whole block.
- */
+ if (iter->oplabelbits) {
/* now check for each operand */
expression *operand = iter->operands;
@@ -2365,9 +2443,9 @@
unsigned offset = find_local_label(lexer, labelid);
unsigned curr_instr = iter->offset;
- /* convert the label identifier into a real label object */
- /* The label offset is calculated deducting the current
Program Counter
- * from the PC of the label.
+ /* convert the label identifier into a real label object.
+ * The label offset is calculated deducting the current
+ * Program Counter from the PC of the label.
*/
operand->expr.l = new_label(lexer, labelid, offset -
curr_instr);
operand->type = EXPR_LABEL;
@@ -2407,7 +2485,7 @@
global_label *glob = find_global_label(lexer, iter->label);
/* if found, then fix it; if not, that's fine, the right instruction
to find the
- * sub during runtime is in place already.
+ * sub during runtime is in place already (i.e. "find_sub_not_null").
*/
if (glob) {
expression *new_second_operand;
@@ -2460,7 +2538,7 @@
if (TEST_FLAG(lexer->subs->flags, SUB_FLAG_MAIN))
new_sub_instr(lexer, PARROT_OP_end, "end");
else {
- /* default sub epilogue */
+ /* default sub epilogue; no return values, hence 0 */
int array_index = generate_signature_pmc(lexer, 0);
new_sub_instr(lexer, PARROT_OP_set_returns_pc, "set_returns_pc");
push_operand(lexer, expr_from_const(lexer, new_const(lexer, INT_TYPE,
array_index)));
@@ -2491,6 +2569,8 @@
/* don't generate the sub epilogue if the last instruction was already
* leaving the sub.
+ * XXX add all instructions that make the sub epilogue unnecessary.
+ * XXX should all branching instructions prevent generation of the
epilogue?
*/
if (CURRENT_INSTRUCTION(lexer)) {
switch (CURRENT_INSTRUCTION(lexer)->opcode) {
@@ -2523,7 +2603,9 @@
* so that invoking ops can find this index.
*/
glob = find_global_label(lexer, CURRENT_SUB(lexer)->info.subname);
+
PARROT_ASSERT(glob != NULL); /* it was stored in new_subr(), so must be
there. */
+
glob->const_table_index = sub_const_table_index;
}
