In order to support massive concurrency efficiently in Java, Orc uses cooperative threading. Orc programs are broken into discrete steps which are executed by a fixed-size thread pool. This approach works for Orc expressions, but the internals of an Orc site written in Java cannot be easily broken down. So Orc has two choices when it needs to call a local Java site:

Fortunately, in practice most Orc site calls take a short, deterministic amount of time to complete. Of those that don't, it's usually only because they are blocked waiting for some external event, like another site call. In this case, instead of blocking the site can return control to the Orc engine, asking to be run again when the external event occurs. In typical Java applications this kind of non-blocking behavior is implemented using callbacks (or in its most general form, continuation passing). Unfortunately this creates convoluted and verbose code: what if you need to block in the middle of a for loop, for example?

Kilim resolves this issue by allowing programmers to write code in a natural blocking style and then rewriting the bytecode to perform a form of CPS conversion, so that instead of blocking the code actually returns control to a scheduler. Orc supports Kilim, allowing site authors to write sites with internal concurrency and blocking behavior which don't use Java threads and cooperate with the Orc engine.

For a full introduction to Kilim, see A Thread of One's Own, by Sriram Srinivasan. In the following, we will cover just enough to get you started writing Orc sites using Kilim.

Kilim introduces three key primitives:

Together, these primitives allow you to write highly-concurrent Java programs in a familiar threaded style. Under the hood, Kilim can schedule any number of concurrent tasks on a fixed number of physical threads, providing better scalability and performance than possible with Java threads.

When writing Orc sites you rarely need to use tasks explicitly because every Orc site call is implicitly run inside a Kilim task if necessary. Therefore all you need to do is mark Pausable methods. Here's a short example of a buffer site written using Kilim Mailboxes:

public class KilimBuffer<V> {
	private LinkedList<Mailbox<V>> waiters =
		new LinkedList<Mailbox<V>>();
	private LinkedList<V> buffer = new LinkedList<V>();
	public synchronized void put(V o) {
		Mailbox<V> waiter = waiters.poll();
		if (waiter != null) waiter.putnb(o);
		else buffer.add(o);
	}
	public synchronized V get() throws Pausable {
		V out = buffer.poll();
		if (out != null) return out;
		else {
			Mailbox<V> waiter = new Mailbox<V>();
			waiters.add(waiter);
			return waiter.get();
		}
	}
}

Classes using Kilim can be imported like other Java classes using the Orc class declaration. For example, we can use the KilimBuffer class defined above:

class Buffer = orc.lib.state.KilimBuffer
val b = Buffer()
  Rtimer(1000) >> b.put("1 second later") >> null
| b.get()

new Foo(bar.pausable());

Object tmp = bar.pausable();
new Foo(tmp);

Sometimes blocking is unavoidable, for example if a site must perform blocking IO. For such cases, Orc provides a utility method orc.runtime.Kilim#runThreaded(Callable) which farms work out to a thread pool. The advantage of doing this over spawning your own thread is that there is no chance of using too many threads; if no thread is available, the method pauses until one becomes available. The disadvantage is that if you have too many Java methods which must communicate with each other concurrently and can't use Mailboxes, there won't be enough threads for them all and execution will deadlock. This situation is sufficiently rare that runThreaded is usually the correct approach.

Code which uses Kilim must be processed with the Kilim "weaver" after compiling and before running. The weaver is bundled with the Orc source code, or may be downloaded separately from the Kilim project site.

To process compiled classes, run kilim.tools.Weaver. If your .class files are in the build/ directory, you would run the weaver like this: java -cp kilim.jar:build/ kilim.tools.Weaver -d build/ build/

The Orc source distribution includes an ant kilim task (in build.xml) which weaves compiled classes in the build directory. If you are compiling Orc in Eclipse, an Eclipse "Builder" is included which does this automatically whenever any source files change.