[svn:parrot] r38815 - trunk/docs/pmc

[coke at svn.parrot.org]

Author: coke
Date: Sat May 16 03:50:07 2009
New Revision: 38815
URL: https://trac.parrot.org/parrot/changeset/38815

Log:
[docs] test/mark more PIR/PASM code.

Many of these are just marked invalid for now. Please fix them!

Modified:
   trunk/docs/pmc/struct.pod

Modified: trunk/docs/pmc/struct.pod
==============================================================================
--- trunk/docs/pmc/struct.pod	Sat May 16 02:26:03 2009	(r38814)
+++ trunk/docs/pmc/struct.pod	Sat May 16 03:50:07 2009	(r38815)
@@ -63,6 +63,8 @@
 
 can be declared with this initializer:
 
+=begin PIR_FRAGMENT_INVALID
+
   new P2, 'ResizablePMCArray'
   .include "datatypes.pasm"
   push P2, .DATATYPE_DOUBLE
@@ -78,19 +80,24 @@
   push P2, 0
   push P2, 0
 
+=end PIR_FRAGMENT_INVALID
+
 =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:
 
+=begin PIR_FRAGMENT_INVALID
+
   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
-  ...
+
+=end PIR_FRAGMENT_INVALID
 
 =head1 Size of a Structure
 
@@ -100,10 +107,14 @@
 
 The size can be obtained by:
 
+=begin PIR_FRAGMENT_INVALID
+
   new P5, 'ManagedStruct', P2   # P2 be some initializer
 
   set I0, P5	# allocated size
 
+=end PIR_FRAGMENT_INVALID
+
 =head1 Accessing Structure Items
 
 Setting or getting items is done by keyed access to the Struct PMC. The first
@@ -112,6 +123,8 @@
 
 =head2 Example
 
+=begin PIR_FRAGMENT_INVALID
+
   set P5[0], N0		# set d
   set N0, P5[0]		# get d
 
@@ -129,6 +142,8 @@
   set S0, P5[3]         # get string at *s
   set S0, P5["s"]	# same
 
+=end PIR_FRAGMENT_INVALID
+
 =head2 Strings
 
 When passing a STRING to a structure that needs a 0-terminated C-string (char
@@ -139,14 +154,22 @@
     char *s;
   };
 
+=begin PIR_FRAGMENT_INVALID
+
   set P5["s"], "a string\x0"
 
+=end PIR_FRAGMENT_INVALID
+
 Please also note, that the C function currently gets a pointer to string
 memory, so any code that might trigger GC should be avoided (or GC turned off).
 Passing constant strings like above is safe though.
 
+=begin PIR_FRAGMENT_INVALID
+
   set P5["s"], S0  # S0 shouldn't move until function call
 
+=end PIR_FRAGMENT_INVALID
+
 =head2 Callback Functions in the C Library
 
 Given a C function that returns a structure containing a callback function like
@@ -161,6 +184,8 @@
 
 The PASM would look like:
 
+=begin PASM_INVALID
+
   push P2, .DATATYPE_FUNC_PTR
   # attach function signature property to this type
   set P1, P2[-1]
@@ -177,6 +202,8 @@
   # call the call_back function
   invoke
 
+=end PASM_INVALID
+
 =head2 Nested Structures or Pointers to Nested Structures
 
 Each contained structure needs its own UnManagedStruct initializer. The
@@ -196,6 +223,8 @@
 
 ... access to elements could look like:
 
+=begin PIR_FRAGMENT_INVALID
+
   # the nested structure
   new P3, 'OrderedHash'
   set P3["i"], .DATATYPE_CHAR
@@ -237,10 +266,16 @@
   set I0, P5["_y"; "j"]
   set I0, P5["z"]
 
+=end PIR_FRAGMENT_INVALID
+
 If the structure has a pointer to another structure the datatype is:
 
+=begin PIR_INVALID
+
   push P2, .DATATYPE_STRUCT_PTR
 
+=end PIR_INVALID
+
 =head1 Passing A Structure to a C function
 
 For a shared library B<libnci_test.so> (or whatever) and a C function
@@ -255,12 +290,16 @@
 
 a pointer to the structure is passed with the B<p> signature char:
 
+=begin PIR
+
   loadlib P1, "libnci_test"
   dlfunc P0, P1, "nci_ip", "ip"
   # P5 is ManagedStruct from above
   invoke
   # I5 is result
 
+=begin PIR
+
 =head1 BUGS
 
 Not all datatypes are implemented. Alignment is barely tested on different