cvsuser 03/07/16 11:18:23
Modified: . core.ops register.c
Log:
Improve documentation on pushing/popping register frames
Revision Changes Path
1.310 +59 -12 parrot/core.ops
Index: core.ops
===================================================================
RCS file: /cvs/public/parrot/core.ops,v
retrieving revision 1.309
retrieving revision 1.310
diff -u -w -r1.309 -r1.310
--- core.ops 16 Jul 2003 01:02:39 -0000 1.309
+++ core.ops 16 Jul 2003 18:18:23 -0000 1.310
@@ -3530,7 +3530,13 @@
=item B<pops>()
Restore all the registers of the type indicated in the name of the operation
-from the most recently B<push>ed copies.
+from the most recently B<push>ed register frames.
+
+A register frame holds only 16 registers, so we pop two frames from the
+frame stack. We use the first frame to restore registers 16-31, and the
+second frame to restore registers 0-15. By restoring in this order, we
+ensure that a C<push> followed by a C<pop> returns the working set of
+registers to their original state.
=cut
@@ -3568,8 +3574,8 @@
=item B<popbottoms>()
-Restores registers 0-15 of the type indicated in the name of the operation
-from the most recently B<push>ed copies.
+Restore registers 0-15 of the type indicated in the name of the operation
+from a register frame popped off the corresponding frame stack.
=cut
@@ -3603,8 +3609,8 @@
=item B<poptops>()
-Restores registers 16-31 of the type indicated in the name of the operation
-from the most recently B<push>ed copies.
+Restore registers 16-31 of the type indicated in the name of the operation
+from a register frame popped off the corresponding frame stack.
=cut
@@ -3639,7 +3645,12 @@
=item B<pushs>()
-Save all the registers of the type indicated in the name of the operation.
+Save all the registers of the type indicated in the name of the operation
+on the appropriate register frame stack.
+
+A register frame holds only 16 registers, so we push two frames onto the
+stack. The first frame holds the values from registers 0-15; the second
+frame holds the values from registers 16-31.
=cut
@@ -3669,6 +3680,7 @@
=cut
+
########################################
=item B<pushtopi>()
@@ -3679,7 +3691,8 @@
=item B<pushtops>()
-Save registers 16-31 on the appropriate register stack
+Save registers 16-31 of the type indicated in the name of the operation
+on the appropriate register frame stack.
=cut
@@ -3705,6 +3718,7 @@
=cut
+
########################################
=item B<pushbottomi>()
@@ -3715,7 +3729,8 @@
=item B<pushbottoms>()
-Save all the registers of the type indicated in the name of the operation.
+Save registers 0-15 of the type indicated in the name of the operation
+on the appropriate register frame stack.
=cut
@@ -4011,19 +4026,51 @@
=item B<saveall>()
-Save all the registers.
+Save all of the registers onto the appropriate frame stacks.
+This op is equivalent to:
+
+ pushi
+ pushn
+ pushs
+ pushp
+
+(or some other permutation of these ops).
=item B<restoreall>()
-Restore all the registers.
+Restore all the registers from the appropriate frame stacks.
+This op is equivalent to:
+
+ popi
+ popn
+ pops
+ popp
+
+(or some other permutation of these ops).
=item B<savetop>()
-Save registers 16-31 of all the register sets
+Save registers 16-31 of all the register sets on the appropriate frame stacks.
+This op is equivalent to:
+
+ pushtopi
+ pushtopn
+ pushtops
+ pushtopp
+
+(or some other permutation of these ops).
=item B<restoretop>()
-Restore registers 16-31 of all the register sets
+Restore registers 16-31 of all the register sets from the appropriate frame
+stacks. This op is equivalent to:
+
+ poptopi
+ poptopn
+ poptops
+ poptopp
+
+(or some other permutation of these ops).
=cut
1.31 +13 -13 parrot/register.c
Index: register.c
===================================================================
RCS file: /cvs/public/parrot/register.c,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -w -r1.30 -r1.31
--- register.c 15 Jun 2003 14:57:29 -0000 1.30
+++ register.c 16 Jul 2003 18:18:23 -0000 1.31
@@ -1,7 +1,7 @@
/* register.c
* Copyright: (When this is determined...it will go here)
* CVS Info
- * $Id: register.c,v 1.30 2003/06/15 14:57:29 leo Exp $
+ * $Id: register.c,v 1.31 2003/07/16 18:18:23 scog Exp $
* Overview:
* Register handling routines
* Data Structure and Algorithms:
@@ -13,7 +13,7 @@
#include "parrot/parrot.h"
/*=for api register Parrot_push_i
- pushes 16 registers worth of int registers onto the int reg stack
+ pushes a new integer register frame onto the corresponding frame stack
*/
void
Parrot_push_i(struct Parrot_Interp *interpreter, void *where)
@@ -45,7 +45,7 @@
}
/*=for api register Parrot_pop_i
- pops 16 integer registers worth of data from the int reg stack
+ pops an integer register frame from the corresponding frame stack
*/
void
Parrot_pop_i(struct Parrot_Interp *interpreter, void *where)
@@ -76,7 +76,7 @@
}
/*=for api register Parrot_clear_i
- sets each register in an integer register frame to 0
+ sets each integer register in the current set to 0
*/
void
Parrot_clear_i(struct Parrot_Interp *interpreter)
@@ -88,7 +88,7 @@
}
/*=for api register Parrot_push_s
- pushes a new string register frame on the frame stack
+ pushes a new string register frame onto the corresponding frame stack
*/
void
Parrot_push_s(struct Parrot_Interp *interpreter, void *where)
@@ -120,7 +120,7 @@
}
/*=for api register Parrot_pop_s
- pops a string register frame off of the frame stack
+ pops a string register frame from the corresponding frame stack
*/
void
Parrot_pop_s(struct Parrot_Interp *interpreter, void *where)
@@ -151,7 +151,7 @@
}
/*=for api register Parrot_clear_s
- sets each register in a string register frame to NULL
+ sets each string register in the current set to NULL
*/
void
Parrot_clear_s(struct Parrot_Interp *interpreter)
@@ -163,7 +163,7 @@
}
/*=for api register Parrot_push_n
- pushes a new numeric register frame on the frame stack
+ pushes a new numeric register frame onto the corresponding frame stack
*/
void
Parrot_push_n(struct Parrot_Interp *interpreter, void *where)
@@ -195,7 +195,7 @@
}
/*=for api register Parrot_pop_n
- pops a numeric register frame off of the frame stack
+ pops a numeric register frame from the corresponding frame stack
*/
void
Parrot_pop_n(struct Parrot_Interp *interpreter, void *where)
@@ -226,7 +226,7 @@
}
/*=for api register Parrot_clear_n
- sets each register in a numeric register frame to 0.0
+ sets each numeric register in the current set to 0.0
*/
void
Parrot_clear_n(struct Parrot_Interp *interpreter)
@@ -238,7 +238,7 @@
}
/*=for api register Parrot_push_p
- pushes a new PMC register frame on the frame stack
+ pushes a new PMC register frame onto the corresponding frame stack
*/
void
Parrot_push_p(struct Parrot_Interp *interpreter, void *where)
@@ -270,7 +270,7 @@
}
/*=for api register Parrot_pop_p
- pops a pmc register frame off of the frame stack
+ pops a PMC register frame from the corresponding frame stack
*/
void
Parrot_pop_p(struct Parrot_Interp *interpreter, void *where)
@@ -301,7 +301,7 @@
}
/*=for api register Parrot_clear_p
- sets each pmc register in a pmc frame stack to NULL.
+ sets each pmc register in the current set to NULL
*/
void
Parrot_clear_p(struct Parrot_Interp *interpreter)
