Fixed unhelpful coredump when parsing (invalid) command-line arguments,
[dyninst.git] / igen / docs / README
1
2 igen - generate RPC calls using <threads/XDR/PVM> as transport.
3
4 This program automates the process of creating remote interfaces.
5 Interfaces are like remote porcedure calls, but the end points
6 can be threads or processes.
7
8 Usage:
9     igen  -xdr | -thread | -pvm [-header | -code]  <inputFileRoot>.I
10
11 Input:
12     A file containing igen protoypes (which are a superset of C++ prototypes).
13
14 Output:
15     1 or 3 three C++ source files.
16     3 header files.
17
18     The header files are:
19         <inputFileRoot>.h      -
20         <inputFileRoot>.CLNT.h -  client class.
21         <inputFileRoot>.SRVR.h -  server class.
22
23     If the interface is thread based, one file is generated.
24         <inputFileRoot>.C
25
26     If the interface is xdr/pvm based, three files are generated.  
27         <inputFileRoot>.C       - xdr/pvm bundlers for the types that can be passed.
28         <inputFileRoot>.CLNT.C  - Client side code for users of the interface.
29         <inputFileRoot>.SRVR.C  - Server code for providers of the interface.
30
31 Note:
32     The member functions declared in <inputFileRoot>.SRVR.h are not generated by
33     igen, except for the class constructor and mainLoop.  These functions are
34     called by the server when it receives a request from the client. These functions
35     must be provided by the programmer.
36
37 An interface looks like:
38
39 $remote <interfaceName> {
40     $base <int>;
41     $version <int>;
42     [$async] <member function definitions>
43     $upcall [$async] <member function definitions>
44 }
45
46 The $base keyword defines the first message tag to use for creating request 
47 and responce message types.  Since TAGS should be unique to an application, 
48 this value should not confilct with other interfaces that might get linked 
49 into the same process.
50
51 The integer after the keyword $version indicates the protocol version of this
52 interface.  For XDR based protocols this version is verified when the client
53 and server rendevous.  For thread based interfaces, igen relies on the fact that
54 changes to an interface generally change the signature of at least one function
55 in the interface, and that version imcompatabilities should be resolved by
56 the C++ linker in that case.
57
58 The member functions are the basis of the interface.  A provider of an interface
59 defines the member functions in the class <interfaceName>.  Igen generates
60 a shadow class <interfaceName>User with the same member functions.  The
61 <interfaceName>User member functions are really RPC style stubs that
62 invoke the remote member functions.
63
64 The $upcall keyword permits interfaces to support upcalls.  Upcalls are a way
65 for an interface to indicate to its user that an "intersting" event has
66 occured.  Upcalls are by default syncchronous, but can be made asynchronous
67 by adding the keyword $async after the keyword $upcall.
68
69 The $async keyword placed before a function definition prevents igen from generating
70 a wait for reply after make the remote procedure call.  No reply will be made by
71 the receiver of the remote procedure call.
72
73