next up previous
Next: Performance Up: JiST- Java in Simulation Previous: Concurrency

API

Many of the important kernel functions have already been mentioned. For completeness, we include the full JiST application interface in Figure 15 and describe it below.

Figure 15: The JiST application programming interface is exposed at the language level via the JistAPI object. The rewriter replaces default noop implementations of the various functions and interfaces with their simulation time equivalents.
\begin{figure}\small
\medskip
\hrulefill\hspace{1ex}{\tt JistAPI.java}\hspace{...
...ce{-2ex}\input{include/JistAPI.java.html}
\vspace{2ex}
\hrule
\end{figure}

JiST API function explanation
   
Entity interface tags a simulation object as an entity, which means that invocations on this object follow simulation time semantics. e.g. jist.swans.mac.MacEntity.
   
Continuation exception tags an entity method as blocking, which means that these entity method invocations will be performed in simulation time, but with continuation. e.g. jist.swans.app.UdpSocket.receive(DatagramPacket).
   
Continuable exception explicitly tags a regular method as possibly blocking, useful only for instances when static analysis can not propagate the blocking property to all callers due to dynamic dispatch. e.g. the abstract method:jist.swans.app.io.InputStream.read().
   
Timeless interface explicitly tags a simulation object as timeless, which means that it will not be changed across simulation time and thus need not be copied when transferred among entities. e.g. jist.swans.node.Message.
   
DoNotRewrite interface tag an object to prevent any rewriter transformations, useful to restrict scope of the rewriter. e.g. jist.minisim.donotrewrite.
   
getTime() returns the local simulation time. The local time is the time of the current event being processed plus any additional sleep time requested during the processing of the current event.
   
END Simulation end time constants, greater than any legal simulation time.
   
sleep(time) advance the local simulation time.
   
end() end simulation after the current time-step.
   
endAt(time) end simulation after given absolute time.
   
callStaticAt(method, params, time) invoke a static method at given simulation time.
   
runAt(runnable, time) invoke a runnable object at given simulation time.
   
THIS entity self-referencing separator, analogous to Java this object self-reference. Should be type-cast before use.
   
ref(entity) returns a separator of a given entity. All statically detectable entity references are automatically converted into separator stubs by the rewriter, so this operator should not be needed. It is included only to deal with rare instances of creating entity types dynamically and for completeness.
   
isEntity(o) returns whether given reference is an entity reference.
   
toString(o) returns the string representation of an object or entity.
   
Proxiable interface an interface used to tag objects that may be proxied. It serves to improve proxying performance by eliminating the need for a relaying wrapper entity.
   
proxy(target, interface) Returns a proxy separator for the given target object and interface class. The proxying approach depends on whether the target is an existing entity, a regular object or a proxiable object. The result is an object whose methods will be relayed to the target in simulation time.
   
proxyMany(target, interface[]) Same as proxy call and allows for multiple interfaces.
   
run(type, name, args, prop) Start a new simulation with given name and arguments at the current time. The supported simulation loader types are Java applications (RUN_CLASS), BeanShell scripts (RUN_BSH), and Jython scripts (RUN_JPY). The properties object carries simulation type-specific information directly to the simulation loader.
   
createChannel() Create a new CSP Channel Entity.
   
setSimUnits(ticks, name) Set the simulation time unit of measure and length in simulation ticks. The default is 1 tick.
   
getTimeString() Return time string in simulation time units.
   
CustomRewriter interface Defines an installable rewriting phase.
   
installRewriter(rewriter) Installs a custom class rewriting phase at the beginning of the JiST rewriting machinery. Used for simulation specific rewriting needs. For example, SWANS uses this interface to rewrite the networking library calls of applications to operate over the simulated network.
   
Logger interface Defines an custom event logger.
   
setLog(logger) Set the simulation logger.
   
log(object) Log an object, usually a string.
   


next up previous
Next: Performance Up: JiST- Java in Simulation Previous: Concurrency
2006-01-18