orc.trace
Class TokenTracer

java.lang.Object
  orc.trace.TokenTracer

All Implemented Interfaces:

Locatable, Located

Direct Known Subclasses:

DerivedTracer.DerivedTokenTracer

public abstract class TokenTracer
extends java.lang.Object
implements Locatable

Interface for writing traces from a single Orc thread. Methods correspond to events which may be traced; in essence this is like a visitor of execution events. Some guidelines used to organize events:

• Steps shared by several logical events are made explicit. So for example when a thread encounters an error, this results in error(TokenException) followed by die(). We could make the die() implicit but making it explicit facilitates code reuse in the client and simplifies queries.
• When two threads interact, at least two events are involved: one for the cause and one for the effect. This ensures that we can reconstruct the behavior of a thread looking only at events in that thread. The effect event includes a pointer back to the cause event.

"Trace" objects (TokenTracer.StoreTrace et al) serve as abstract handles for events and are used to record relationships between events in different threads. Since Java doesn't have existential types, implementors have to cast these objects to the appropriate concrete types internally. This is safe as long as all the TokenTracers produced by a single Tracer use use compatible concrete trace types.

Author:

quark

Nested Class Summary

static interface	TokenTracer.PullTrace Abstract handle for a pull event
static interface	TokenTracer.StoreTrace Abstract handle for a store event

Constructor Summary

TokenTracer()

Method Summary

abstract void	block(TokenTracer.PullTrace pull) Block a thread waiting for a future.
abstract void	choke(TokenTracer.StoreTrace store) Killed through the setting of a future.
abstract void	die() Terminate a thread.
abstract void	enter(Closure closure) Enter a closure.
abstract void	error(TokenException error) Report an error.
abstract TokenTracer	fork() Create a new thread.
abstract void	leave(int depth) Leave "depth" closures EXPERIMENTAL
abstract void	print(java.lang.String value, boolean newline) Print to stdout.
abstract void	publish(java.lang.Object value) Publish a value from the program.
abstract TokenTracer.PullTrace	pull() Create a new future for a pull.
abstract void	receive(java.lang.Object value) Return from a site call.
abstract void	send(java.lang.Object site, java.lang.Object[] arguments) Call a site.
abstract TokenTracer.StoreTrace	store(TokenTracer.PullTrace event, java.lang.Object value) Store a value for a future.
abstract void	unblock(TokenTracer.StoreTrace store) Receive a future we were waiting for.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface orc.error.Locatable

setSourceLocation

Methods inherited from interface orc.error.Located

getSourceLocation

Constructor Detail

TokenTracer

public TokenTracer()

Method Detail

fork

public abstract TokenTracer fork()

Create a new thread. By convention the new thread should evaluate the right side of the combinator.

die

public abstract void die()

Terminate a thread.

send

public abstract void send(java.lang.Object site,
                          java.lang.Object[] arguments)

Call a site.

store

public abstract TokenTracer.StoreTrace store(TokenTracer.PullTrace event,
                                             java.lang.Object value)

Store a value for a future. The return value should be used when tracing the results of this store. If this returns null, clients are free to not call choke(StoreTrace).

The engine guarantees that all choke(orc.trace.TokenTracer.StoreTrace) and unblock(orc.trace.TokenTracer.StoreTrace) events will occur before the die() event for this tracer.

See Also:

choke(orc.trace.TokenTracer.StoreTrace), unblock(orc.trace.TokenTracer.StoreTrace)

choke

public abstract void choke(TokenTracer.StoreTrace store)

Killed through the setting of a future. Should be followed by die().

receive

public abstract void receive(java.lang.Object value)

Return from a site call. Should be called after send(Object, Object[]).

block

public abstract void block(TokenTracer.PullTrace pull)

Block a thread waiting for a future.

unblock

public abstract void unblock(TokenTracer.StoreTrace store)

Receive a future we were waiting for.

print

public abstract void print(java.lang.String value,
                           boolean newline)

Print to stdout.

publish

public abstract void publish(java.lang.Object value)

Publish a value from the program. Should be followed by die().

error

public abstract void error(TokenException error)

Report an error. Should be followed by die().

pull

public abstract TokenTracer.PullTrace pull()

Create a new future for a pull. Should be followed by fork().

enter

public abstract void enter(Closure closure)

Enter a closure. EXPERIMENTAL

leave

public abstract void leave(int depth)

Leave "depth" closures EXPERIMENTAL