protocol.txt

OTP是开放电信平台的简称

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.