diff options
Diffstat (limited to 'lib/ic/internal_doc/protocol.txt')
| -rw-r--r-- | lib/ic/internal_doc/protocol.txt | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/lib/ic/internal_doc/protocol.txt b/lib/ic/internal_doc/protocol.txt new file mode 100644 index 0000000000..54e1ef55cf --- /dev/null +++ b/lib/ic/internal_doc/protocol.txt @@ -0,0 +1,182 @@ +Peter Hogfeldt 2003-08-18 PA3 + +THE IC PROTOCOL + +1 INTRODUCTION + + The IDL Compiler (IC) transforms Interface Definition Language + (IDL) specifications files to interface code for Erlang, C, and + Java. The Erlang language mapping is described in the Orber + documentation, while the other mappings are described in the IC + documentation (they are of course in accordance with the CORBA C + and Java language mapping specifications, with some restrictions). + + The most important parts of an IDL specification are the operation + declarations. An operation defines what information a client + provides to a server, and what information (if any) the client + gets back from the server. We consider IDL operations and language + mappings in section 2. + + What we here call the IC protocol, is the description of messages + exchanged between IC end-points (client and servers). It is valid + for all IC back-ends, except the 'erl_plain' and 'erl_corba' + back-ends. The protocol is described in section 3. + + The IC protocol is in turn embedded into the Erlang gen_server + protocol, which is described in section 4. + + Finally, the gen_server protocol is embedded in the Erlang + distribution protocol. Pertinent parts of that protocol is + described in section 5. + + +2 LANGUAGE MAPPINGS AND IDL OPERATIONS + +2.1 IDL Operations + + An IDL operation is declared as follows: + + [oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN, + out OType1 O1, out OType2 O2, ..., out OTypeM OM) + N, M = 0, 1, 2, ... (2.1.1) + + `Op' is the operation name, RetType is the return type, and ITypei, + i = 1, 2, ..., N, and OTypej, j = 1, 2, ..., M, are the `in' types + and `out' types, respectively. The values I1, I2, ..., IN are + provided by the caller, and the value of RetType, and the values + O1, O2, ..., OM, are provided as results to the caller. + + The types can be any basic types or derived types declared in the + IDL specification of which the operation declaration is a part. + + If the RetType has the special name `void' there is no return + value (but there might still be result values O1, 02, ..., OM). + + The `in' and `out' parameters can be declared in any order, but + for clarity we have listed all `in' parameters before the `out' + parameters in the declaration above. + + If the keyword `oneway' is present, the operation is a cast, i.e. + there is no confirmation of the operation, and consequently there + must be no result values: RetType must be equal to `void', and M = + 0 must hold. + + Otherwise the operation is a call, i.e. it is confirmed (or else + an exception is raised). + + Note carefully that an operation declared without `oneway' is + always a call, even if RetType is `void' and M = 0. + +2.2 Language Mappings + + There are several CORBA Language Mapping specifications. These are + about mapping interfaces to various programming languages. IC + supports the CORBA C and Java mapping specifications, and the + Erlang language mapping specified in the Orber documentation. + + Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide: + + Functions with return type void will return the atom ok. + + Excerpt from "6.13 Invocations of Operations" in the Orber User's Guide: + + A function call will invoke an operation. The first parameter + of the function should be the object reference and then all in + and inout parameters follow in the same order as specified in + the IDL specification. The result will be a return value + unless the function has inout or out parameters specified; in + which case, a tuple of the return value, followed by the + parameters will be returned. + + Hence the function that is mapped from an IDL operation to Erlang + always have a return value (an Erlang function always has). That + fact has influenced the IC protocol, in that there is always a + return value (which is 'ok' if the return type was declared 'void'). + + +3 IC PROTOCOL + + Given the operation declaration (2.1.1) the IC protocol maps to + messages as follows, defined in terms of Erlang terms. + +3.1 Call (Request/Reply, i.e. not oneway) + + request: Op atom() N = 0 + {Op, I1, I2, ..., IN} tuple() N > 0 + (3.1.1) + + reply: Ret M = 0 + {Ret, O1, O2, ..., OM} M > 0 + (3.1.2) + + Notice; Even if the RetType of the operation Op is declared to be + 'void', a return value 'ok' is returned in the reply message. That + return value is of no significance, and is therefore ignored (note + however that a C server back-end returns the atom 'void' instead + of 'ok'). + +3.2 Cast (oneway) + + notification: Op atom() N = 0 + {Op, I1, I2, ..., IN} tuple() N > 0 + (3.2.1) + (There is of course no return message). + +3.3 Propagation of Exceptions + + Currently there is no propagation of exceptions from the server to + the client. As it is now a an exception detected by the server + will hang the client in a receive. That is unacceptable. + + Exception propagation is only meaningful for Call (request/reply). + + +4 GEN_SERVER PROTOCOL + + Most of the IC generated code deals with encoding and decoding the + gen_server protocol. + +4.1 Call + + request: {'$gen_call', {self(), Ref}, Request} (4.1.1) + + reply: {Ref, Reply} (4.1.2) + + where Request and Reply are the messages defined in 3.1 Call. + +4.2 Cast + + notification: {'$gen_cast', Notification} (4.2.1) + + where Notification is the message defined in 3.2 Cast. + + +5 ERLANG DISTRIBUTION PROTOCOL + + Messages (of interest here) between Erlang nodes are of the form: + + Len(4), Type(1), CtrlBin(N), MsgBin(M) (5.1) + + Type is equal to 112 = PASS_THROUGH. + + CtrlBin and MsgBin are Erlang terms in binary form (as if created + by term_to_binary/1), whence for each of them the first byte is + equal to 131 = VERSION_MAGIC. + + CtrlBin (of interest here) contains the SEND and REG_SEND control + messages, which are binary forms of the Erlang terms + + {2, Cookie, ToPid} , (5.2) + + and + + {6, FromPid, Cookie, ToName} , (5.3) + + respectively. + + The CtrlBin(N) message is read and written by erl_interface code + (C), j_interface code (Java), or the Erlang distribution + implementation, which are invoked from IC generated code. + + The MsgBin(N) is the "real" message, i.e. of the form described + in section 4. |