For concreteness, we show the trace log records generated for a simple distributed program. Our example program implements a procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer’s account is in good standing, and the delivery options are up to date. An object residing in the "buyer" process (or vat) has remote references to objects residing in the "product" and "accounts" vats. The buyer queries the remote objects with asynchronous (non-blocking) message sends. The answers from the asynchronous inquiries must be collected and examined. The order is placed only if all requirements are satisfied.

For concreteness, we show the trace log records generated for a simple distributed program. Our example program implements a procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer’s account is in good standing, and the delivery options are up to date. An object residing in the "buyer" process (or vat) has remote references to objects residing in the "product" and "accounts" vats. The buyer queries the remote objects with asynchronous (non-blocking) message sends. The answers from the asynchronous inquiries must be collected and examined. The order is placed only if all requirements are satisfied.

-

-

Starting with one-way asynchronous messages, two patterns for handling responses are ''continuation-passing'' and ''promises''. In continuation-passing a request carries a callback argument to which a response should be sent.

-

We refer to this as ''Ajax-style'' messaging, as it is the dominant pattern for web application development. A promise (''future'', in AmbientTalk) is a place-holder for the answer to a query; when the answer becomes available the promise resolves to that value.

-

-

Waterken, AmbientTalk and Causeway support both styles of response handling.

-

-

This program is one of the examples that can be browsed in the Causeway viewer. It is implemented in AmbientTalk and Waterken/Java. Here, we use the Waterken version. Starting with the simplest case, i.e., Causeway's "Hello World", we build up to a promise-based implementation.

-

-

It is written in Java and ran on the Waterken web server.

-

=== Getting Started ===

=== Getting Started ===

Line 19:

Line 9:

* See [[Causeway]] for user documentation, which includes instructions for launching Causeway from a command line shell.

* See [[Causeway]] for user documentation, which includes instructions for launching Causeway from a command line shell.

-

* See HP Labs Technical Report at www.hpl.hp.com/techreports/2009/HPL-2009-78.html for a more in-depth discussion of the material presented here. A careful read is not necessary but a quick skim to see what's there is a good idea.

+

* Enable Causeway's debug view.

-

This documentation assumes an understanding of the purchase-order example program.

+

Setting Causeway's debug flag enables a debug view. As events are selected in the viewer, the debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.

+

<pre>

+

$ rune -Dcauseway_debug=true causeway.e-swt

+

</pre>

-

* Read the source code. It's part of the E distribution and can be found here.

+

('''Note:''' When this debug option is set, Causeway's JSON parser uses <tt>getTwine()</tt>. This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)

-

<code>e/src/esrc/scripts/test/causeway/waterken/sources</code>

-

<code>e/src/esrc/scripts/test/causeway/ambientTalk/sources</code>

-

Also, we're asking that you write a version of the purchase-order example that runs on your platform, as one of your first test cases. It's best to start with the Ajax-style continuation-passing, using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

Setting Causeway's debug flag enables a debug view. As events are selected in the viewer, the debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.

+

The example is written for the AmbientTalk and Waterken platforms. Select Help >> Open Waterken Example (Simple Ajax-style). This is the simplest implementation, i.e., Causeway's "Hello World". We start here and work up to the promise-based implementation.

-

<pre>

+

-

$ rune -Dcauseway_debug=true causeway.e-swt

+

-

</pre>

+

+

('''Note:''' Starting with one-way asynchronous messages, two patterns for handling responses are ''continuation-passing'' and ''promises''. In continuation-passing a request carries a callback argument to which a response should be sent.

+

We refer to this as ''Ajax-style'' messaging, as it is the dominant pattern for web application development. A promise (''future'', in AmbientTalk) is a place-holder for the answer to a query; when the answer becomes available the promise resolves to that value.)

-

('''Note:''' When this debug option is set, Causeway's JSON parser uses <tt>getTwine()</tt>. This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)

+

* Read the source code. It's part of the E distribution and can be found here.

+

<code>e/src/esrc/scripts/test/causeway/waterken/sources</code>

+

<code>e/src/esrc/scripts/test/causeway/ambientTalk/sources</code>

-

[[Image:debug-view.png]]

+

If instrumenting a platform, your first test case should be the purchase-order example, ported to run on your platform. Start with the Ajax-style using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

For concreteness, we show the trace log records generated for a simple distributed program. Our example program implements a procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer’s account is in good standing, and the delivery options are up to date. An object residing in the "buyer" process (or vat) has remote references to objects residing in the "product" and "accounts" vats. The buyer queries the remote objects with asynchronous (non-blocking) message sends. The answers from the asynchronous inquiries must be collected and examined. The order is placed only if all requirements are satisfied.

Getting Started

See Causeway for user documentation, which includes instructions for launching Causeway from a command line shell.

Enable Causeway's debug view.

Setting Causeway's debug flag enables a debug view. As events are selected in the viewer, the debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.

$ rune -Dcauseway_debug=true causeway.e-swt

(Note: When this debug option is set, Causeway's JSON parser uses getTwine(). This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)

Open the purchase-order example program in the Causeway viewer.

The example is written for the AmbientTalk and Waterken platforms. Select Help >> Open Waterken Example (Simple Ajax-style). This is the simplest implementation, i.e., Causeway's "Hello World". We start here and work up to the promise-based implementation.

(Note: Starting with one-way asynchronous messages, two patterns for handling responses are continuation-passing and promises. In continuation-passing a request carries a callback argument to which a response should be sent.
We refer to this as Ajax-style messaging, as it is the dominant pattern for web application development. A promise (future, in AmbientTalk) is a place-holder for the answer to a query; when the answer becomes available the promise resolves to that value.)

Read the source code. It's part of the E distribution and can be found here.

If instrumenting a platform, your first test case should be the purchase-order example, ported to run on your platform. Start with the Ajax-style using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

Causeway's Trace Log Format

Causeway supports the trace log format defined by Tyler Close at waterken.sourceforge.net/debug/.

Logging Ajax-style Messaging in Waterken

The code snippet below shows the 3 queries being fired off. All 3 answers must be examined before the order is placed. Collecting the answers is handled by an AsyncAnd object. To collect the three answers, teller is passed as an argument to each of the remote queries, serving as a callback function.

anchor uniquely identifies the origin of this message send as the 2nd messaging event from the buyer vat, turn 3.

message is a generated string which uniquely identifies a message.

trace is the stack capture at the point of the message send.

(Note: The loop field identifies the vat by URI. By convention, Causeway picks up the part following "/-/", in this case buyer, for a short display name.)

(Note: The timestamp field is optional. Currently, Causeway ignores it, so it's not shown in the remaining trace records.)

The corresponding Got has a matching message. The message delivery in the product vat starts a new turn, turn 2. Being at the top of a new turn, there is limited stack capture and getting a source span through Java reflection, is not practical.

Reporting true to teller has two log entries: a Sent and its corresponding Got.