aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/internal_doc/protocol.txt
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/ic/internal_doc/protocol.txt
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/ic/internal_doc/protocol.txt')
-rw-r--r--lib/ic/internal_doc/protocol.txt182
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.