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