New igen features.
[dyninst.git] / igen / docs / NEW_IGEN
1
2 New features in Igen.
3
4 1) Arrays must be declared before they are used.  
5 2) No more Strings 
6 3) Pointers
7 4) Classes
8 5) Type checking for xdr code, thread code.
9 6) Examples
10 7) Recursive data structures
11
12 1) Arrays must be declared before they are used.
13     Why:  Try specifying a pointer to an array of pointers
14           to type char*.
15
16           function ($array char* *cantParse);  
17   
18           How are the "*"s get parsed? 
19
20   The syntax is:
21     $remote array <Array_type> <ptrs> <Array_name>;
22          <Array_type>: identifier, must be "known" if xdr code
23                        is being generated
24          <ptrs>: 0 or more "*"s
25          <Array_name>: identifier, to keep the names consistent
26                        with those that have been used, append
27                        "_Array" to the end of the element type.
28
29     The data structure generated is the same.
30
31 2) No more Strings 
32     There had been a typedef in rpcUtil.h, "typedef char* String"
33     The reason for its existence was to allow igen to treat char*
34     as a special case, since it did not allow pointers to any 
35     basic types.  It still does not allow pointers to basic types
36     (for xdr code), but "char*" is allowed (for xdr code).
37
38     Since String_Array is used throughout paradyn, the .I files 
39     contain "array char * String_Array;"
40
41 3) Pointers
42     Xdr code can now handle pointers to classes and pointers to
43     structures.  One level of indirection is allowed.  Pointers
44     to arrays are also acceptable.
45
46     Pointers can cause problems.  If a recursive data structure
47     is passed into an igen bundler, the bundler may not return.
48
49 4) Classes
50     Igen can generate classes.  The syntax is...
51
52     $remote class <className> [: <parent> ] { 
53     <member variables>
54     [ $ignore $ignore ]
55     };
56
57     An example is...
58     $remote class1 {
59         int a;
60         int b;
61     };
62
63     $remote class2 : class1 {
64           // these are public member variables (FOR NOW)
65         char z;
66         char x;
67         $ignore
68           // text between the ignore tokens will be passed thru to the client 
69           // and the server
70           // this is the current solution to allow member functions to be defined
71           getX() { return x;}
72         $ignore
73     };
74
75     Inheritance is supported for the caller and callee.
76     More information will be provided on this at a later data.
77
78 5) Type checking for xdr code, thread code.
79     Igen does not care about the type names used if you are generating
80     thread code because igen does not generate any bundlers when thread
81     code is used.  If you specify a type name that is unknown, the compiler,
82     not igen, will inform you.
83
84     Igen is concerned about the type names used when xdr code is being 
85     generated since it must generate bundlers for those types.  The basic
86     rule is that a type name must be a basic type (ie, float or integer), 
87     or it must be a type that has been defined using igen keywords:
88     $remote array, $remote class, $remote typedef.
89
90 6) Examples
91    igen/tests has plenty of purified examples.
92
93 7) Recursive data structures
94    igen can handle recursive data structures.  However, it igen bundlers
95    will currently go into an endless loop if it attempts to bundle a 
96    recursive data structure.  If you need this support, let me know.