Pyjama — Quick Start

Background motivating Pyjama, plus what you need to install and use it.

1. Motivation

1.1 Why parallel computing?

Parallel computing arrived on mainstream desktop systems as multi-core processors, because of the difficulty of maintaining improvements in uni-processor clock speed. Users see no performance improvement unless their applications are parallelised, and parallel programming is notoriously difficult — especially for correctness and high performance.

1.2 Object-oriented programming and (sequential) iterators

The most popular languages are object-oriented, especially for general-purpose desktop applications, and iterative computations carry much of the computational load. Consider:

Collection<File> elements = ...
Iterator<File> it = elements.iterator();
while (it.hasNext()) {
    File file = it.next();
    processFile(file);
}

This uses only one thread. Parallelising it manually raises questions of scheduling policy, implementation, correctness, and performance — the simplest schemes are least efficient, the most efficient most error-prone.

2. Preparation

2.1 What you need

Pyjama is a pure Java project supporting both desktop and Android environments. Before you start, install the Java Development Kit (JDK 1.6 suggested). The latest release can be downloaded here.

2.2 Pyjama installation and usage

If you download the source, compile it and create pyjama.jar first. The build uses an Apache Ant script (build.xml); you’ll need Ant installed and the required libraries (PTCompiler.jar, PTRuntime.jar, ParaIterator.jar) placed in a lib folder. If you download pyjama.jar directly, all dependencies are packed together.

Using the compiler. Write Java code in a file with the .pj extension; the corresponding .java file is produced (compile it with javac). Never edit the generated .java files — your changes are lost on recompilation:

> java -jar pyjama.jar:. package/MyClass.pj
> javac -cp pyjama.jar:. package/MyClass.java
> java -cp pyjama.jar:. package.MyClass

Classpath. Include pyjama.jar on your classpath. The main class you’ll interact with is java_omp.Pyjama (e.g. for thread IDs).

Refreshing. The compiler sometimes introduces new classes; update your classpath or, in an IDE such as Eclipse, refresh the source folder so the generated .java files compile.

Known limitations. The compiler implements many common OpenMP features. The following directives are believed fairly stable (with some clause-ordering requirements):

//#omp atomic
//#omp parallel [async] [if (expr)] [dataClauseList]
//#omp for [dataClauseList] [schedule] [ordered] [nowait]
//#omp parallel for [async] [if (expr)] [dataClauseList] [schedule] [ordered] [nowait]
//#omp ordered
//#omp section
//#omp sections [dataClauseList] [nowait]
//#omp parallel sections [async] [if (expr)] [dataClauseList] [nowait]
//#omp single [dataClauseList]
//#omp master
//#omp critical [identifierName]
//#omp barrier
//#omp flush [(argumentList)]

Data clauses include private, firstprivate, lastprivate, shared, and reduction; schedules are static, dynamic, or guided. Not yet supported: //#omp threadprivate, nesting of parallel regions (the runtime ignores much nesting), and specifying team size per region (the runtime always creates a team equal to the number of detected processors). The biggest known instability is complex use of data clauses across nested regions — keep them simple.

2.3 Pyjama Eclipse Plugin installation and usage

An Eclipse plugin is also available — see the Eclipse Plug-In page. After installing, create a new Pyjama project via File → New → Other… and choose the Pyjama project wizard, or convert an existing Java/Android project by adding the Pyjama nature and converting .java files to .pj. The plugin understands the project type and generates code specific to Desktop or Android, automatically translating .pj to .java and compiling it.

3. Pyjama examples

See the Examples page for the Hello World, Mandelbrot Set, and EvoLisa applications.