CSP2JR(1)

NAME
csp2jr - CSP notation to JR code preprocessor

SYNOPSIS
csp2jr [-ti] [-te] file.csp

DESCRIPTION

Csp2jr converts a program written in CSP (Communicating Sequential Processes) notation into an equivalent one written in the JR language. The CSP program named x must be placed in the file x.csp. From that, csp2jr produces x.jr program, which the user can then translated using the JR and Java translators (e.g., jr x). (Do not use csp2jr to translate any non-CSP code.) Csp2jr also places several files whose names begin with csp_ in the current directory. -t options specify which termination discipline is to be used.

The exact syntax of the CSP notation can be discerned by examining the CSP programs in the examples directory. Each CSP-notation construct begins with an underscore; CSP code is mixed with regular JR code.

Csp2jr translates a CSP program into an equivalent JR class with a main method. The translated program's main method creates an instance of the JR class. First, though, it invokes the hook method (see details under QUICK REFERENCE below), if one was specified. The hook method can be used, for example, to access command line arguments, read data to initialize variables, and set the quiescence operation. Given that an instance of the JR class is created, the CSP program can use static or non-static variables. However, static variables are recommended so that they can be used within the hook method and the quiescence operation.

The JR generated code uses a slight modification of the centralized clearing house technique described in Andrews's book. The generated code is not necessarily fair; i.e., ports are serviced nondeterministically.

Csp2jr supports implicit (i.e., automatic) or explicit termination disciplines. The choice is made by the corresponding command line option. The default is implicit termination. If a CSP input/output command that appears as a statement (e.g., _i as a separate statement, not one within an _if or _do) fails, the entire program terminates. A process that attempts to send to or receive from itself is detected as a run-time error.

Following are a few restrictions in using csp2jr . CSP processes can have 0, 1, or 2 dimensions. The subscripts for arrays of processes must be integers; arrays are 0-based as in Java. All specs (for processes and their ports) must appear before any process body. Code for all members of a process family must be the same. Nested processes are not allowed. JR operation names are used as CSP constructors (i.e., CSP message port types). There is no empty constructor. Operation names must be unique to a process. Parameters must be enclosed in `()' even if there are none.

The boolean part of a CSP guard can be only a single boolean expression; so, use `&&' to separate parts of a guard (not `;' as in the original CSP notation). Quantifier variables should not be declared. There can be 1 or 2 quantifiers. Variables cannot be declared as part of guards. The CSP _if and _do constructs do not allow an else part. The CSP _do construct does not allow exit or next statements.

A few limitations exist to ease the implementation. Do not use names of JR predefined functions or reserved words (e.g., cap) as variable names within CSP code. Do not use identifiers beginning with csp_ within CSP code. Do not use any other JR synchronization or return/reply within a CSP program.

Csp2jr generates some JR code at the end of each process. If the CSP process code contains an infinite loop (e.g., while(true){...}), then the JR compiler will give an error that the code generated after the loop is unreachable. To circumvent that error, use, e.g., boolean go = true; while(go){...}).

The predefined Java method Thread.sleep, which puts the currently executing process to sleep for a while and performs a context switch to another process, is useful in CSP programs to alter the interleaving of process execution. For example, it can be used with the random number functions to obtain different interleavings to test whether a critical section algorithm works. See the programs in the examples directory for examples.

QUICK REFERENCE
_program name { code }
_program name _main hook { code }
	hook will be invoked before any CSP process begins;
	it is useful for accessing command line arguments and
	possibly reading global data from a file;
	it must not be named main;
	it must be declared static void hook(String [] args) {...}

_specs { process_specs} }
	Each process_specs specifies a process or process family:
		name	single CSP process
		name [s1]	one-dim CSP process array name[s1]
		name [s1][s2]	two-dim CSP process array name[s1][s2]
	and a list of ports for that process or process family:
		{ ports }
	Each ports specifies a port:
		oname(ospec);
	A port declaration is similar to an operation declaration in JR
	(but it does not specify a return type or void).

_dump_pidx	for implementation debugging

_process name { code }
	body of process name
_process name (v1) { code }
	one-dim body; v1 is process id
_process name (v1,v2) { code }
	two-dim body; v1,v2 is process id

_i pname?ouse(args);
	input statement
	pname is source; ouse is port name; args are formals
_i [v1 = l1 _to u1] pname?ouse(args);
	one-dim quantified input statement
_i [v1 = l1 _to u1]  [v2 = l2 _to u2] pname?ouse(args);
	two-dim quantified input statement

_o pname!ouse(args);
	output statement
	pname is destination; ouse is port name; args are actuals
_o [v1 = l1 _to u1] pname!ouse(args);
	one-dim quantified output statement
_o [v1 = l1 _to u1]  [v2 = l2 _to u2] pname!ouse(args);
	two-dim quantified output statement

_if		CSP if, for using I/O in guards
	don't separate guards with []
_fi

_do		CSP do, for using I/O in guards
	don't separate guards with []
_od

_g (expr)	plain boolean guard of _if or _do
_g [v1 = l1 _to u1] (expr)	one-dim quantified guard
_g [v1 = l1 _to u1]  [v2 = l2 _to u2] (expr)	 two-dim quantified guard

_i (expr) pname?ouse(args) { code }
	input guard with block of code
	pname is source; ouse is port name; args are formals
_i [v1 = l1 _to u1] (expr) pname?ouse(args) { code }
	one-dim quantified input guard with block of code
_i [v1 = l1 _to u1]  [v2 = l2 _to u2]  (expr) pname?ouse(args) { code }
	two-dim quantified output guard with block of code

_o (expr) pname!ouse(args) { code }
	output guard with block of code
	pname is destination; ouse is port name; args are actuals
_o [v1 = l1 _to u1] (expr) pname!ouse(args) { code }
	one-dim quantified output guard with block of code
_o [v1 = l1 _to u1]  [v2 = l2 _to u2]  (expr) pname!ouse(args) { code }
	two-dim quantified output guard with block of code

_csp_status(brief)
	output execution status of all CSP processes; useful for debugging.
	boolean parameter brief controls level of detail of output.

FILES
file.csp    CSP notation source file
file.jr    generated JR source file
csp_*.jr    additional JR files

SEE ALSO
Ronald A. Olsson and Aaron W. Keen, The JR Programming Language: Concurrent Programming in an Extended Java. Kluwer Academic Publishing (now part of Springer), 2004, ISBN 1-4020-8085-9. (see http://www.cs.ucdavis.edu/~olsson/research/jr).

Gregory R. Andrews and Ronald A. Olsson, The SR Programming Language: Concurrency in Practice. Benjamin/Cummings, 1993, ISBN 0-8053-0088-0.

Gregory R. Andrews, Concurrent Programming: Principles and Practice. Benjamin/Cummings, 1991, ISBN 0-8053-0086-4.

jr(1), csp2sr(1), ccr2sr(1), m2sr(1) ccr2jr(1), m2jr(1)

DIAGNOSTICS
Some erroneous CSP code will cause errors from csp2jr. These line numbers generally correspond to the ones in the .csp file.

Other errors in CSP code are detected by the JR or Java compilers. The line numbers for these errors will not correspond to those in the original source file, but they can be mapped back by looking in the generated code file. The generated code file contains as comments the original lines of source code along with the source file name and source line number. Thus, the line in the original source file can be located fairly easily. If, for example, the JR compiler reports an error on line 38, then look at line 38 of the generated JR file. Above that line, you might find a comment
// a.csp, line 12  x = y+2;
This is the line that immediately caused the error.