Fixed unhelpful coredump when parsing (invalid) command-line arguments,
[dyninst.git] / igen / docs / igen.1
1 .TH IGEN 1L PARADYN "6 July 1994"
2 .SH NAME
3 igen \- RPC Interface Generator
4 .SH SYNOPSIS
5 .B
6 igen \-xdr | \-thread | \-pvm [\-header | \-code] <input root>.I 
7
8 .SH DESCRIPTION
9 .PP
10 This program automates the process of creating remote procedure call 
11 interfaces.  The client and server of the interface can be processes or
12 threads.
13 .SH OPTIONS
14 .TP 8
15 .B \-xdr
16 This option specifies that \fBigen\fP should use XDR as the transport
17 mechanism.
18 .TP 8
19 .B \-thread
20 This option specifies that \fBigen\fP should use threads messages as
21 the transport mechanism.
22 .TP 8
23 .B \-pvm
24 This option specifies that \fBigen\fP should use pvm as the the
25 transport mechanism.
26 .TP 8
27 .B\-code
28 This option specifies that \fBigen\fP should only generate the source files.
29 .TP 8
30 .B\-header
31 This option specifies that \fBigen\fP should only generate the header files.
32 .TP 8
33 .B <input root>.I
34 This file specifies the interface template to use to generate the source and
35 header files.  All files will use <input root> in their name.  
36
37 .SH "OUTPUT"
38 .PP
39 \fBigen\fP produces the following output files:
40 .TP 8
41 .B Source Files
42 One file is generated if the interface is thread based, <input root>.C
43
44 Three files are generated if the interface is xdr/pvm based:
45
46 <input root>.C  - xdr/pvm bundlers for the types that can be passed.
47
48 <input root>.CLNT.C     - Client side code for users of the interface.
49
50 <input root>.SRVR.C     - Server code for providers of the interface.
51 .TP 8
52 .B Header Files
53 The header files are:
54
55         <input root>.h
56
57         <input root>.CLNT.h - client class
58
59         <input root>.SRVR.h - server class.
60 .TP 8
61 .B Note:
62 The member functions declared in <input root>.SRVR.h are not generated by
63 igen, except for the class constructor and mainLoop.  These functions are
64 called by the server when it receives a request from the client. These
65 functions must be provided by the programmer.
66
67 .SH "MEMORY"
68 .PP
69
70 igen frees all memory that it allocates, with one exception.  Return types in
71 the client code may be a structure or an array class.  The memory allocated
72 for these return types will not be deallocated by igen.  
73
74 .SH "UPCALLS"
75 .PP
76
77 Upcalls from the server to the client are supported.  However, the upcalls
78 will only be seen when the client is waiting for a response from a synchronous
79 call to the server.  There is a way to force the client to attempt to handle
80 an upcall.  The client has a member function awaitResponce which will handle
81 any upcall requests that exist, but awaitResponce will block.  The file descriptor should be checked to see if it is ready for reading before calling
82 awaitResponce.
83
84 .SH "INTERFACE TEMPLATE"
85 .PP
86 An interface looks like:
87
88 $remote <interfaceName> {
89     $base <int>;
90     $version <int>;
91     $virtual [$async | $array] <member function definitions>
92     $virtual $upcall [$async] <member function definitions>
93     $cmember type variable;
94     $smember type variable;
95 }
96
97 The $array keyword causes igen to genarate an array class and use this as
98 the array type.  The class has a member specifying the size of the array
99 and a pointer to the data.
100
101 The $virtual keyword causes the igen generated functions to be declared virtual.  For upcalls, the client function is declared virtual.  For non-upcalls, the server function is declared virtual.
102
103 The $smember and $cmember keywords cause igen to put the type and variable declaration into the client or server class.  $smember specifies that the server class is to include the type and variable as a public data member.  $cmember specifies that the client class is to include the type and variable as a public data member.
104
105 The $base keyword defines the first message tag to use for creating request 
106 and responce message types.  Since TAGS should be unique to an application, 
107 this value should not confilct with other interfaces that might get linked 
108 into the same process.
109
110 The integer after the keyword $version indicates the protocol version of this
111 interface.  For XDR based protocols this version is verified when the client
112 and server rendevous.  For thread based interfaces, igen relies on the fact that
113 changes to an interface generally change the signature of at least one function
114 in the interface, and that version imcompatabilities should be resolved by
115 the C++ linker in that case.
116
117 The member functions are the basis of the interface.  A provider of an interface
118 defines the member functions in the class <interfaceName>.  Igen generates
119 a shadow class <interfaceName>User with the same member functions.  The
120 <interfaceName>User member functions are really RPC style stubs that
121 invoke the remote member functions.
122
123 The $upcall keyword permits interfaces to support upcalls.  Upcalls are a way
124 for an interface to indicate to its user that an "interesting" event has
125 occured.  Upcalls are by default synchronous, but can be made asynchronous
126 by adding the keyword $async after the keyword $upcall.
127
128 The $async keyword placed before a function definition prevents igen from generating
129 a wait for reply after make the remote procedure call.  No reply will be made by
130 the receiver of the remote procedure call.
131
132 .SH "EXAMPLE"
133 .PP
134 An example interface is:
135
136 #define PASS_THRU "this hash-define gets passed through"
137
138 /* a struct with one int */
139 .br
140 $remote typedef struct { 
141 .br
142     int style;
143 .br
144 } intStruct;            
145
146 $remote typedef struct {
147 .br
148     int computer;
149 .br
150     int science;
151 .br
152 } mStruct;
153
154 /*
155 .br
156  *
157 .br
158  */
159 .br
160 $remote test {
161 .br
162     $base 2000;
163 .br
164     $version 1;
165 .br
166     void nullNull();                            // a comment
167 .br
168     int intNull();
169 .br
170     $async void nullStruct(intStruct);
171 .br
172     int intString(String);
173 .br
174     int add(int, int);
175 .br
176     int sumVector($array int);
177 .br
178     $array int retVector(int len, int start);
179 .br
180     String stringString(String);
181 .br
182     void triggerSyncUpcall(int val);
183 .br
184     $upcall void syncUpcall(int x);
185 .br
186     // this function will be virtual in the server class
187 .br
188     $virtual void triggerAsyncUpcall(int val);
189 .br
190     // this function will be virtual in the client class
191 .br
192     $virtual $upcall $async void asyncUpcall(int x);
193 .br
194     // int happy; will be a public data member in the client
195 .br
196     $cmember int happy;
197 .br
198     // int sad; will be a public data member in the server
199 .br
200     $smember int sad;
201 .br
202 };
203
204 .SH "SEE ALSO"
205 Paradyn(1).
206 .SH COPYRIGHT
207 Copyright 1994, The Paradyn Software Team.
208 .SH AUTHOR
209 Jeff Hollingsworth (hollings@cs.wisc.edu)
210 .br
211 Mark Callaghan     (markc@cs.wisc.edu)
212
213
214