cvsuser 03/12/25 05:00:29
Modified: . MANIFEST
Added: docs/pmc struct.pod
Log:
docu for struct PMCs
Revision Changes Path
1.520 +1 -0 parrot/MANIFEST
Index: MANIFEST
===================================================================
RCS file: /cvs/public/parrot/MANIFEST,v
retrieving revision 1.519
retrieving revision 1.520
diff -u -w -r1.519 -r1.520
--- MANIFEST 19 Dec 2003 16:42:33 -0000 1.519
+++ MANIFEST 25 Dec 2003 13:00:18 -0000 1.520
@@ -227,6 +227,7 @@
docs/pmc/perlarray.pod [main]doc
docs/pmc/perlhash.pod [main]doc
docs/pmc/perlstring.pod [main]doc
+docs/pmc/struct.pod [main]doc
docs/pmc/subs.pod [main]doc
docs/running.pod [main]doc
docs/strings.pod [main]doc
1.1 parrot/docs/pmc/struct.pod
Index: struct.pod
===================================================================
=head1 NAME
Structures - Accessing C Structs from Parrot
=head1 DESCRIPTION
Parrot provides two PMC classes to deal with C structures. These
are UnManagedStruct and ManagedStruct. The former hasn't any allocated
memory and is typically used to access structures returned by NCI calls,
while the latter can be used to define a structure and pass it over
to a C function - pointers to structures in both cases of course.
=head1 Structure definition
The Struct PMCs take an array of triples per structure element, either
as initializer or with the B<assign> opcode to define the struct elements.
=over 4
=item Datatype
The datatype is defined by constants declared in B<datatypes.pasm>.
=item Array Size
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.
=back
=head2 Example
The C structure
struct {
double d;
float f;
int i[4];
};
is declared with this initializer:
new P2, .PerlArray
.include "datatypes.pasm"
push P2, .DATATYPE_DOUBLE
push P2, 0 # no array i.e. 1 element
push P2, 0 # calculate offset by just adding item size
push P2, .DATATYPE_FLOAT
push P2, 0
push P2, 0
push P2, .DATATYPE_INT
push P2, 4 # 4 elem array
push P2, 0
=head1 Calculating the Size of a Structure
For ManagedStruct (a new structure passed over to a C function) the
storage for data items has to be allocated. This can be done like
in the following example:
=head2 Example
new P5, .ManagedStruct, P2
set I6, 0
sizeof I7, .DATATYPE_DOUBLE
add I6, I7
sizeof I7, .DATATYPE_FLOAT
add I6, I7
sizeof I7, .DATATYPE_INT
mul I7, 4
add I6, I7
set P5, I6 # allocate size
If packing of structure items produces holes, they have to be accounted
for.
=head1 Accessing Structure Items
Setting or getting items is done by keyed access to the Struct PMC. The
first key is the structure item, an optional second key can access the
n-th array element.
=head2 Example
set P5[0], N0 # set d
set N0, P5[0] # get d
set P5[1], N1 # set f
set N1, P5[1] # get f
set P5[2;0], I2 # set i[0]
set I3, P5[2;3] # get i[3]
=head1 Passing A Structure to a C function
For a shared library B<libnci.so> (or whatever) and a C function
typedef struct _dfi_t {
double d;
float f;
int i[4];
} dfi_t;
int nci_ip(dfi_t *p) {}
a pointer to the structure is passed with the B<p> signature char:
loadlib P1, "libnci"
dlfunc P0, P1, "nci_ip", "ip"
# P5 is ManagedStruct from above
invoke
# I5 is result
=head1 BUGS
Only a few datatypes are implemented.
=head1 FILES
F<classes/unmanagedstruct.pmc>, F<classes/managedstruct.pmc>
=head1 SEE ALSO
F<docs/pdds/pdd03_calling_conventions.pod>
F<t/pmc/nci.t>
=head1 AUTHOR
Leopold Toetsch <[EMAIL PROTECTED]>
