orc.trace
Interface TokenTracer

All Superinterfaces:

Locatable, Located

All Known Implementing Classes:

DerivedTracer.DerivedTokenTracer

public interface TokenTracer
extends 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.BeforeTrace Abstract handle for a before event
static interface	TokenTracer.PullTrace Abstract handle for a pull event
static interface	TokenTracer.StoreTrace Abstract handle for a store event

Method Summary

void	after(TokenTracer.BeforeTrace before) Indicate that the right side of a semicolon combinator is continuing.
TokenTracer.BeforeTrace	before() Leaving the left side of a semicolon combinator.
void	block(TokenTracer.PullTrace pull) Block a thread waiting for a future.
void	choke(TokenTracer.StoreTrace store) Killed through the setting of a future.
void	die() Terminate a thread.
void	enter(Closure closure) Enter a closure.
void	error(TokenException error) Report an error.
TokenTracer	fork() Create a new thread.
void	leave(int depth) Leave "depth" closures EXPERIMENTAL
void	print(java.lang.String value, boolean newline) Print to stdout.
void	publish(java.lang.Object value) Publish a value from the program.
TokenTracer.PullTrace	pull() Create a new future for a pull.
void	receive(java.lang.Object value) Return from a site call.
void	send(java.lang.Object site, java.lang.Object[] arguments) Call a site.
TokenTracer.StoreTrace	store(TokenTracer.PullTrace event, java.lang.Object value) Store a value for a future.
void	unblock(TokenTracer.StoreTrace store) Receive a future we were waiting for.
void	useStored(TokenTracer.StoreTrace storeTrace) Called when a token reads a value from a group cell which has already been stored.

Methods inherited from interface orc.error.Locatable

setSourceLocation

Methods inherited from interface orc.error.Located

getSourceLocation

Method Detail

fork

TokenTracer fork()

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

die

void die()

Terminate a thread.

send

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

Call a site.

store

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

void choke(TokenTracer.StoreTrace store)

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

receive

void receive(java.lang.Object value)

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

block

void block(TokenTracer.PullTrace pull)

Block a thread waiting for a future.

unblock

void unblock(TokenTracer.StoreTrace store)

Receive a future we were waiting for.

print

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

Print to stdout.

publish

void publish(java.lang.Object value)

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

error

void error(TokenException error)

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

pull

TokenTracer.PullTrace pull()

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

before

TokenTracer.BeforeTrace before()

Leaving the left side of a semicolon combinator. If the thread is "leaving" because it is dying, this will be followed by a die(); otherwise it may be followed by any number of events which happen outside the scope of the semicolon.

Returns:

a tag which you can pass to after(BeforeTrace).

enter

void enter(Closure closure)

Enter a closure. EXPERIMENTAL

leave

void leave(int depth)

Leave "depth" closures EXPERIMENTAL

after

void after(TokenTracer.BeforeTrace before)

Indicate that the right side of a semicolon combinator is continuing.

Parameters:

before - the BeforeEvent which triggered this event

useStored

void useStored(TokenTracer.StoreTrace storeTrace)

Called when a token reads a value from a group cell which has already been stored.

Parameters:

storeTrace - the trace produced when store(orc.trace.TokenTracer.PullTrace, Object) was called