cvsuser 04/02/05 03:07:40
Modified: classes unmanagedstruct.pmc
docs/pmc struct.pod
Log:
update struct.pod
Revision Changes Path
1.27 +2 -1 parrot/classes/unmanagedstruct.pmc
Index: unmanagedstruct.pmc
===================================================================
RCS file: /cvs/public/parrot/classes/unmanagedstruct.pmc,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -w -r1.26 -r1.27
--- unmanagedstruct.pmc 5 Feb 2004 10:24:02 -0000 1.26
+++ unmanagedstruct.pmc 5 Feb 2004 11:07:35 -0000 1.27
@@ -1,7 +1,7 @@
/*
* Copyright: 2001-2003 The Perl Foundation. All Rights Reserved.
* CVS Info
- * $Id: unmanagedstruct.pmc,v 1.26 2004/02/05 10:24:02 leo Exp $
+ * $Id: unmanagedstruct.pmc,v 1.27 2004/02/05 11:07:35 leo Exp $
* Overview:
* PMC class to hold structs that parrot's not responsible for
* disposing of.
@@ -14,6 +14,7 @@
* Initial revision by sean 2002/08/04
* Notes:
* References:
+ * F<docs/pmc/struct.pod>
*/
#include "parrot/parrot.h"
1.2 +51 -10 parrot/docs/pmc/struct.pod
Index: struct.pod
===================================================================
RCS file: /cvs/public/parrot/docs/pmc/struct.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -w -r1.1 -r1.2
--- struct.pod 25 Dec 2003 13:00:29 -0000 1.1
+++ struct.pod 5 Feb 2004 11:07:39 -0000 1.2
@@ -23,19 +23,31 @@
=item Array Size
-The second initializer item if set to a value greater then 1 defines
+The second initializer item, if set to a value greater then 1, defines
the struct element to consist of an array of the given data type.
=item Byte Offset
-The third initializer is the byte offset of the data item in the
-structure. This entry can be 0 if packing of the structure is aligned to
-the items sizes. Otherwise these offsets must be set correctly as Parrot
-doesn't know, how your C compiler packs arbitray data. Parrot only knows
-the size of each item.
+The third initializer is the byte offset of the data item in the structure.
+This entry can be 0 if packing of the structure is aligned to the item's sizes
+or the alignment is the item's size. Otherwise these offsets must be set
+correctly as Parrot doesn't know, how your C compiler packs arbitray data.
+Parrot only knows the size of each item.
=back
+=head2 Alignment
+
+Parrot tries to do The Right Thing that is currently align items at
+their size.
+
+ struct {
+ char c;
+ int i;
+ }
+
+The B<i> above is aligned at 4 (for i386 or such).
+
=head2 Example
The C structure
@@ -46,7 +58,7 @@
int i[4];
};
-is declared with this initializer:
+can be declared with this initializer:
new P2, .PerlArray
.include "datatypes.pasm"
@@ -60,6 +72,20 @@
push P2, 4 # 4 elem array
push P2, 0
+=head2 Named Structure Elements
+
+The initializer can be an OrderedHash PMC too. When all elements are
+defined in the correct order this can be used to define and access
+struct elements by name and by index:
+
+ new P2, .OrderedHash
+ .include "datatypes.pasm"
+ set P2["d"], .DATATYPE_DOUBLE
+ push P2, 0 # no array i.e. 1 element
+ push P2, 0 # calculate offset by just adding item size
+ set P2["f"], .DATATYPE_FLOAT
+ ...
+
=head1 Calculating the Size of a Structure
For ManagedStruct (a new structure passed over to a C function) the
@@ -82,7 +108,18 @@
set P5, I6 # allocate size
If packing of structure items produces holes, they have to be accounted
-for.
+for - but see below.
+
+The calculation can be simplified a bit, by accessing the offset of the
+last item and only adding the size of that. (When an initializer is
+assigned to the struct, zero offsets are recalculated).
+
+So for above example:
+
+ set I6, P2[8] # offset of 3rd struct element i[4]
+ sizeof I7, .DATATYPE_INT
+ mul I7, 4
+ add I6, I7 # I6 is now the total size
=head1 Accessing Structure Items
@@ -95,13 +132,17 @@
set P5[0], N0 # set d
set N0, P5[0] # get d
+ set N0, P5["d"] # get d if initializer is an OrderedHash
+
set P5[1], N1 # set f
set N1, P5[1] # get f
-
+ set N1, P5["f"] # get f if initializer is an OrderedHash
set P5[2;0], I2 # set i[0]
set I3, P5[2;3] # get i[3]
+ set P5["i"; 2] # set i[2] if initializer is an OrderedHash
+
=head1 Passing A Structure to a C function
For a shared library B<libnci.so> (or whatever) and a C function
@@ -124,7 +165,7 @@
=head1 BUGS
-Only a few datatypes are implemented.
+Only a few datatypes are implemented. Alignment is buggy.
=head1 FILES
