diff options
Diffstat (limited to 'lib/ic/internal_doc/protocol.txt')
| -rw-r--r-- | lib/ic/internal_doc/protocol.txt | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/lib/ic/internal_doc/protocol.txt b/lib/ic/internal_doc/protocol.txt deleted file mode 100644 index 54e1ef55cf..0000000000 --- a/lib/ic/internal_doc/protocol.txt +++ /dev/null @@ -1,182 +0,0 @@ -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. |