[e-lang] Causeway JSON format doc? (attn Tyler Close and Terry Stanley)

Tyler Close tyler.close at gmail.com
Fri Aug 1 09:46:29 CDT 2008

Hi Kevin,

Answers inline below...

On Fri, Aug 1, 2008 at 5:43 AM, Kevin Reid <kpreid at mac.com> wrote:
> On Aug 1, 2008, at 0:54, Tyler Close wrote:
>> The log format is defined by the set of "data" classes at:
>> <http://waterken.sourceforge.net/javadoc/org/ref_send/log/package-summary.html>
>> The org.waterken.syntax.json package defines a serialization from Java
>> record classes to JSON. So the Causeway JSON trace file format is the
>> serialization of any object tree you can compose from the classes
>> linked to above.
> OK. My further questions then are:
> * Is this format intended to be usable by systems other than ref_send?
> I had understood that the new Causeway format was, but this system
> appears to be not very flexible in the matter of what information must
> be available.

This format is intended to be language neutral and is currently being
used in both Java and E. Brian Warner was also reviewing the format
for use in Python and didn't raise any flags. I don't understand your
comment above. What flexibility has been lost?

> * Where do I (as a log generator) put the *content* of the messages
> (what object they are delivered to, what the verb and arguments are)?

The verb is included in the stack trace. The other information is not
used by the Causeway viewer. If you came up with a use for this
information, you could add it to the format by extending the Sent

> * I now see that the anchor.turn.number field is not the causing
> event, as I had assumed it was. Where do I put cause information, then?

The anchor member of an Event documents where the Event was received.
As you've noted below, different kinds of events are caused in
different ways. Some events don't have any cause at all, like a
Comment. More on this further down...

> I get the impression that it is constructed out of the association of
> Sent and Got events -- that is, Sent has the event in which the
> message was sent and Got is the event of its delivery -- but then:

Correct. A simple message send is represented as a pair of events: a
Sent and a Got. They each carry the same GUID, so they can be matched

>   * How do I express Resolver#gettingCloser?
>   * How do I express the N causes of a buffered message? That is,
> when a promise is resolved, each message delivered to its target has
> at least two causes (in the original log format): the event(s) of the
> original send, and the event of the resolution. I get the impression
> that this is handled by SentIf and Resolved, but I don't see how this
> can express the case of a promise resolved to another promise, in that
> the Resolved event does not identify the new "condition".

A message queued on a promise is represented as a SentIf, followed by
a Resolved, followed by a Got.

In ref_send, I am representing a promise resolved to another promise
by a separate turn for each queued message on the resolved promise
that does a SentIf on the resolved to promise. I suggest you do the

Again, the Causeway viewer doesn't use any representation of object
identity, which I suspect is causing you more confusion here.

> * When is nonprimitive -- exactly what stage is expected to generate
> SentIf events?

A SentIf is generated by execution of a when, or an eventual send on a
promise. A Resolved is generated when the promise is resolved. A Got
is generated when the when block is executed, or the eventual send is

> * Which promises are expected to generate Resolved events?

Any promise that becomes resolved should generate a Resolved event.

> (I'm a little bit bothered by these last three questions -- it seems
> to me that the new log format requires a lot more information to be
> tracked by the implementation to fit its structure, while not
> providing much benefit in amount of useful information available to
> the debugger. I may well be just not seeing it yet.)

Actually, it's the opposite. The log format allows the debugger to be
ignorant of promises, as the current Causeway viewer is, and only
process Sent and Got events. In such an implementation, a SentIf is
treated the same as a Sent.

I don't understand your complaint above. In fact, Terry reported
significant code reduction when switching Causeway to this format.

> * http://waterken.sourceforge.net/javadoc/org/ref_send/log/
> CallSite.html does not state how lines and columns are counted:

I suggest we defer to the Unicode standard:


>   * Zero or one-based column numbers?


>   * Is the column counting scalar values or grapheme clusters?

Unicode code points.

>   * What are considered line breaks?

See above.

> * What is expected to be in the "name" field in a CallSite?

Whatever makes sense for the source language. For Java, I'm using the
name of the containing method.

> * What is the benefit of the Anchor.number field -- is it not implicit
> in the ordering of items in the log?

Who says all the items end up in the same file, or that they are even
in a file at all. I could imagine a useful implementation that dumps
the records into a relational, or RDF database.

> Comments:
> * Have you considered using a log format that doesn't require a
> termination at the end of the file, i.e. "]"? This requirement means
> that a log file is invalid if a vat's implementation is shut down
> abnormally, and there must be code to wrap up the file explicitly.

So don't use a single file. Use a separate file for each burst of output.


More information about the e-lang mailing list