[e-lang] CapTP in E: beginning and progress report

[Kevin Reid]

I have started work on a CapTP implementation in E.

I have begun by translating most of the MIT-licensed portions of  
CapTP (comm tables and NonceLocator) to E. I am currently working on  
the reimplementation of CapTPConnection.


Questions that came up, since answered by MarkM (mostly not verbatim):

Q. What is rdrBase in NewRemotePromiseDesc?

A. rdr is a Redirector created by the receiving side for the sender  
to use to resolve the promise. rdrBase is a SwissBase for that  
redirector, provided so that the sending side can construct a  
reference to it which is passable to another vat, without waiting for  
any roundtrips from the receiver.


Q. Is there any difference between an ImportsTable and a QuestionsTable?

A. None, other than the method ImportsTable#store/2 which is only in  
that class.


Q. Where are the wireCounts stored?

A. CommTable's "myFreeList". See the comment for that field.


Q. What does the "jcomm" in "net.captp.jcomm" mean?

A. MarkM: 'It meant "a temporary Java implementation of a captp comm  
system until I can replace it with an E-based implementation"'


Q. What exactly does int#cryptoHash/0 compute?

A. The unsigned integer interpretation of the SHA-1 hash of the  
smallest possible octet array holding the big-endian two's complement  
representation of the recipient.


Q. What does ShutdownOp mean?

A. The connection should be closed iff the recipient has not sent any  
more messages than the specified number. This is used for GCing  
connections, and must not be visible to user code (must not break  
references). MarkM: 'The funny case is messages to be sent to zero  
when a shutdown might happen. These need to be buffered, so that if a  
shutdown does happen, that can be resent transparently on a newly  
formed connection.'


Comments on the code:

SwissTable#getNewSwiss/1's name and documentation are wrong: for  
selfish objects the swiss number is *not* fresh.


Comments on the documentation:

<http://www.erights.org/elib/distrib/captp/4tables.html> fails to  
explain clearly what it means by "h < 0" etc. It's hard to go from  
this documentation to the understanding that e.g. any DeliverOp's  
first argument is negative, and why this is so.

It is confusing that the descriptor & helper object pages (e.g.  
http://www.erights.org/elib/distrib/captp/Far3Desc.html ) repeat the  
row format on the index page, but provide a different and further- 
useful hyperlink.

<http://www.erights.org/elib/distrib/captp/DeliverOp.html>: "The  
wireCounts exists to solve a race condition problem that will be  
explained at GCExportOp, but in this scenrio it suffices to say that  
the sent wireCount will be "1"." -- the explanation seems to exist on  
the DeliverOp page rather than GCExportOp.

-- 
Kevin Reid                            <http://homepage.mac.com/kpreid/>