This document is the specification for the JCSP core API.

JCSP provides a complete library for building complex functionality through layered networks of communicating processes. It conforms to the CSP model of cummunicating systems so that twenty years of theory, tools and practical experience can be brought to bear in the support of Java multi-threaded applications. Newcomers to JCSP should start with the documentation on the {@link org.jcsp.lang.CSProcess `CSProcess`} interface, which outlines and motivates the notion of components as communicating processes and the process oriented design pattern.

Processes interact solely via CSP synchronising primitives, such as {@link org.jcsp.lang.Channel channels} ({@link org.jcsp.lang.One2OneChannel one-to-one}, {@link org.jcsp.lang.Any2OneChannel any-to-one}, {@link org.jcsp.lang.One2AnyChannel one-to-any}, {@link org.jcsp.lang.Any2AnyChannel any-to-any}), {@link org.jcsp.lang.One2OneCallChannel CALL channels}, {@link org.jcsp.lang.CSTimer timers}, {@link org.jcsp.lang.Crew crews}, {@link org.jcsp.lang.Barrier barriers}, {@link org.jcsp.lang.AltingBarrier alting barriers}, {@link org.jcsp.lang.Bucket buckets} or other well-defined modes of access to shared passive objects. Processes do not invoke each other's methods. Processes may be combined to run in {@link org.jcsp.lang.Sequence sequence} or {@link org.jcsp.lang.Parallel parallel}. Processes may be combined to wait passively on a number of {@link org.jcsp.lang.Alternative alternative} events, with one of them trigered into action only by the external generation of that event. Such collections of events may be serviced either {@link org.jcsp.lang.Alternative#fairSelect() fairly} (guaranteeing no starvation of one event by the repeated arrival of its siblings), by any user-defined {@link org.jcsp.lang.Alternative#priSelect() priority} or in an {@link org.jcsp.lang.Alternative#select() arbitrary} manner.

JCSP is an alternative to the built-in monitor model for Java threads. JCSP primitives should not normally be mixed into designs with `synchronized` method declarations, instances of the `java.lang.Runnable` interface or `java.lang.Thread` class, or invocations of the `wait`/`notify`/`notifyAll` methods from `java.lang.Object`.

However, JCSP is compatible with the built-in model and, with care, can be mixed safely and profitably. In particular, process communication via `wait`-free `synchronized` method invocations on a shared passive object directly implements a common CSP server idiom (see {@link org.jcsp.awt.DisplayList `DisplayList`} for an example). Further, existing libraries that interact with user software via listener registration and callback (such as the standard AWT and Swing) can be easily tailored to operate as processes with channel-based interfaces (for example, see {@link org.jcsp.awt org.jcsp.awt}).

Finally, we note that the JCSP library reflects the occam-pi realisation of CSP and pi-calculus., An occam-pi `PROC` declaration maps simply into a class implementing {@link org.jcsp.lang.CSProcess `CSProcess`}, whose constructor parameters mirror the `PROC` parameters and whose `run` method mirrors the `PROC` body.

## Acknowledgements

This JCSP library is being developed from work originally carried out and presented by numerous individuals at the WoTUG Java Threads Workshop and conferences (WoTUG-20, WoTUG-21, WoTUG-22, WoTUG-23/CPA-2000, WoTUG-24/CPA-2001, WoTUG-25/CPA-2002, WoTUG-26/CPA-2003, WoTUG-27/CPA-2004, WoTUG-28/CPA-2005, WoTUG-29/CPA-2006, WoTUG-30/CPA-2007, WoTUG-31/CPA-2008) in the period 1996-2008 and continuing. Please follow the links to find the original sources. Special thanks are owed to Paul Austin, who developed the original JCSP library.

## References

`Communicating Sequential Processes', C.A.R. Hoare, CACM, 21-8, pp. 666-677, August 1978.

> This is the original exposition of CSP. Presentation is largely from the programmer's point of view. The Ada tasking model and the occam/transputer process model were derived from this work.

`Communicating Sequential Processes', C.A.R. Hoare, Prentice Hall, 1985.

> This is `the book'. Presentation is more abstract (i.e. mathematical) and a more general theory is given than in the original CACM paper. One crucial difference is that events (and channels) become concepts that are separate from the processes that engage in them. This difference was adopted in the occam/transputer model, but Ada missed out on it. The JCSP library follows the model presented in this book.

`The Theory and Practice of Concurrency', A.W. Roscoe, Prentice Hall, ISBN 0-13-674409-5, 1997.

> This brings CSP up to date with refinements developed over the past decade. It is `the new book'.

`Communicating Sequential Processes and Deadlock' J.M.R.Martin, Chapter 1 from his Ph.D thesis ("The Design and Construction of Deadlock-Free Concurrent Systems"), University of Buckingham, UK, 1996.

> This gives a crisp, amusing and accurate tour around all the CSP concepts, strongly recommended for beginners and experienced CSP users alike. [Actually only up to (and including) page 11 are for normal mortals - after that it starts to get scary. But those first few pages are a gem.]

`A Classical Mind - Essays in Honour of C.A.R. Hoare', Edited by A.W. Roscoe, Prentice Hall, ISBN 0-13-294844-3, 1994.

> Serious bedtime reading.

`Parallel Processing with Communicating Process Architecture', I.R.East, UCL press, ISBN 1-85728-239-6, 1995.

> This is an excellent text on how to design and program with the CSP model - many higher level design issues are addressed.

`occam 2 -- including occam 2.1', John Galletly, UCL press, ISBN 1-85728-362-7, 1996.

> This is a good textbook on the occam version of the CSP model. A knowledge of occam gives insight that makes multithreading in Java simpler and, hence, safer to manage ;-) ...

`Parallel and Distributed Computing in Education', P.H.Welch, in Proceedings of VecPar'98, Lecture Notes in Computer Science #1573, Springer-Verlag, April 1999.

> This is a tutorial introduction to CSP from the point of view of the programmer/designer. JCSP bindings to key examples are given in an appendix. See Abstract.

`Java Threads in the Light of occam/CSP', P.H.Welch, in Architectures, Languages and Patterns for Parallel and Distributed Applications, Proceedings of WoTUG-21, pp. 259-284, IOS Press (Amsterdam), ISBN 90 5199 391 9, April 1998.

> This is a tutorial introduction to the Java monitor model. It raises concern over its ease of use and the safety of its standard design patterns, but shows how it may be used to build the CSP primitives. Finally, it revisits those concerns and shows how they fade in the light of CSP. See Abstract.

## Request for Feedback

Currently, the more complex the system requirements, the less likely it becomes that concurrency (or multi-threading) play a major role. This is because concurrency is thought to make system design especially hard - so many additional problems (race hazards, deadlock etc.) to worry about. A good model of concurrency, however, should simplify the design, implementation, verification and maintenance of systems. A design goal for our CSP-for-Java collaboration is to enable concurrency to play that natural role. Feedback on moving towards that goal is always welcome.