netobj/src/netobjrt/StubConn.i3


 Copyright 1992 Digital Equipment Corporation.               
 Distributed only by permission.                             
 StubConn.i3 
 Last modified on Mon Nov  7 12:34:49 PST 1994 by wobber  
      modified on Wed Dec  2 11:40:50 PST 1992 by gnelson 
      modified on Wed Jun 24 11:12:25 PDT 1992 by owicki 

A StubLib.Conn represents a bi-directional connection used to invoke remote methods by the network objects runtime. Here we reveal that a connection c consists of a message reader c.rd and a message writer c.wr.\ttindex{StubLib.Conn}

Connections come in matching pairs; the two elements of the pair are typically in different address spaces. If c1 and c2 are paired, the target of c1.wr is equal to the source of c2.rd, and vice versa. Thus the messages written to c1.wr can be read from c2.rd, and vice versa.

INTERFACE StubConn;

IMPORT MsgRd, MsgWr, StubLib;

REVEAL StubLib.Conn <: Public;

TYPE
  T = StubLib.Conn;      (* compatibility with old stub generator, remove *)
  Public = OBJECT rd: MsgRd.T; wr: MsgWr.T END;

END StubConn.
Clients can use this interface to bypass the procedures in the StubLib interface and marshal and unmarshal arguments using inline code, for example to write directly to the underlying writer. To do this, import the RdClass and WrClass interfaces\cite{Modula3} to reveal the internal structure of readers and writers. You will have to be careful about locks. All readers and writers contain an internal lock used to serialize operations. It is a requirement of the StubLib interface that all parameters of type Conn be passed with both streams unlocked. It is a further requirement that no client thread operate on the streams while an activation of a StubLib procedure is in progress.

There are two final clauses in the specification of the message readers and message writers that appear in a StubConn.T. First, their buffers must be word-aligned in memory. More precisely, if byte i in the data stream is stored in the buffer at memory address j, then i and j must be equal modulo the machine word size. This requirement allows optimized stubs to read and write scalar values from the buffer efficiently. Second, their buffers must not be too small. More precisely, when the nextMsg method of a writer returns, there must be at least 24 bytes of free space in the writer buffer, and when the nextMsg method of a reader returns, there must be at least 24 bytes of message data in the reader buffer. This requirement allows the runtime to efficiently read and write the headers required by the network object protocol.\index{buffered streams}