aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/internal_doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ic/internal_doc')
-rw-r--r--lib/ic/internal_doc/c-improvements-1.txt84
-rw-r--r--lib/ic/internal_doc/protocol.txt182
2 files changed, 0 insertions, 266 deletions
diff --git a/lib/ic/internal_doc/c-improvements-1.txt b/lib/ic/internal_doc/c-improvements-1.txt
deleted file mode 100644
index ccfdec7cbe..0000000000
--- a/lib/ic/internal_doc/c-improvements-1.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-Peter Hogfeldt 2003-08-14 PA1
-
-IC C BACK-ENDS IMPROVEMENTS
-
-1 C CLIENT
-
-1.1 Cast
-
- Each oneway operation roughly consists of the following code
- parts:
-
- - encoding the cast message
- - setting index of the out buffer to zero (1.1.1)
- - encoding the magic (1.1.1)
- - encoding a tuple header of size 2 (1.1.1)
- - encoding '$gen_cast' (1.1.1)
- - encoding the operation parameters (1.1.2)
- - sending the cast message (1.1.3)
-
- Only (1.1.2) is unique for the operation in question.
-
-1.1.1 Todo
-
- Define functions:
-
- int oe_ei_encode_cast(CORBA_environment *) that performs (1.1.1)
-
- int oe_ei_cast(CORBA_environment *) that performs (1.1.3)
-
- This will reduce code size.
-
- As compiler options
-
- oe_ei_encode_cast(), and
- oe_ei_cast()
-
- may be replaced by user defined functions.
-
-1.2 Call
-
- Each (non-oneway) operation roughly consists of the following code
- parts:
-
- - encoding the call message
- - setting index of the out buffer to zero (1.2.1)
- - encoding the magic (1.2.1)
- - encoding a tuple header of size 3 (1.2.1)
- - encoding '$gen_call' (1.2.1)
- - encoding a tuple header of size 2 (1.2.1)
- - encoding the from pid (1.2.1)
- - encoding the unique ref (1.2.1)
- - encoding the operation parameters (1.2.2)
- - sending the call message (1.2.3)
- - receiving the reply message (1.2.3)
- - decoding the reply parameters (1.2.4)
-
- Only (1.2.2) and (1.2.4) are unique for the operation in question.
-
-1.2.1 Todo
-
- Define functions:
-
- int oe_ei_encode_send(CORBA_environment *) that performs (1.2.1)
-
- int oe_ei_send_and_receive(CORBA_environment *) that performs (1.2.3)
-
- This will reduce code size.
-
- As compiler options
-
- oe_ei_encode_send(), and
- oe_ei_send_and_receive()
-
- may be replaced by user defined function.
-
-
-2 SERVER
-
- We do not provide any code for receiving operation messages, execute
- operations, and send the result back. Should we not do that?
-
-
-
- \ No newline at end of file
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.