M2JR(1)

NAME
m2jr - monitor notation to JR code preprocessor

SYNOPSIS
m2jr [-sc] [-sw] [-su] [-sx] file.m

DESCRIPTION

M2jr converts a monitor written in monitor notation into equivalent code written in the JR language. The monitor named x must be placed in the file x.m. From that, m2jr produces x.jr. This translated code along with JR code that uses the monitor (which must be in a separate .jr file) may then be translated by using jr(1). (Do not use m2jr to translate the code that uses the monitor or any non-monitor code.) The -s options specify which monitor signaling discipline is to be used.

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

M2jr translates a monitor into an equivalent JR class; the JR generated code uses a slight modification of the technique described in Joe Herman's thesis. Typically, the rest of the user's code will be a single JR class; that code needs to instantiate an instance or instances of the monitor (class). Monitor operations must be declared in _proc declarations.

M2jr supports SC (signal and continue), SX (signal and exit), SW (signal and wait), and SU (signal and urgent wait) signaling disciplines. The choice is made by the corresponding command line option. The default is SC.

The operations on condition variables are the standard ones: wait(cv), _wait(cv)(rank) (i.e., prioritized wait), signal(cv), empty(cv), minrank(cv), and signal_all(cv). (signal_all only makes sense in the SC signaling discipline; it is not allowed in the others). For the SX discipline, each signal must be immediately followed (lexically) by a monitor return statement, _return (even if the signal is the last statement within a monitor _proc). For all _return statements, monitor exclusion is released just before the return, so any value being returned should be local to the proc to avoid potential races. In addition, print(cv), intended for primitive debugging, outputs the number of processes waiting on the condition variable and their ranks.

Condition variables are declared as _condvar cv. Arrays of condition variables can be declared too, e.g., condvar scan[2] declares scan to be a one dimensional array with indices 0 and 1, and condvar foo[3][4] declares foo to be a two dimensional array with indices 0 through 2 in the first dimension and 0 through 3 in the second dimension.

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 monitors. Do not use identifiers beginning with m_ within monitor code. Do not use any other JR synchronization or return/reply within a monitor program.

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 monitor 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.

Note that Java itself provides a form of monitor, but it does not provide the various signaling disciplines and its signal (``notify'') chooses the process to awaken non-deterministically. As in most traditional definitions of monitors, the signal in all m2jr signaling disciplines is first-come, first-served.

QUICK REFERENCE
_monitor name { code}

_condvar x	declare condition variable x
_condvar x[s]	declare one-dim array condition variable x[s]
_condvar x[s][t]	declare two-dim array condition variable x[s][t]

_var ...	place before each monitor "permanent"
	variable declaration

_proc x { code }	monitor procedure with prototype x

_wait(cv)
_wait(cv)(r)	prioritized wait by rank r on condition variable cv
_empty(cv)
_minrank(cv)
_print(cv)	(for debugging; not a regular monitor primitive)

_signal(cv)
_signal_all(cv)	(only for SC signaling discipline)
_return
_return expr
	(monitor exclusion is released just before
	the return, so expr should be local to the proc
	to avoid potential races.)

FILES
file.m    monitor notation source file
file.jr    generated JR source file
m_*.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), ccr2sr(1), csp2sr(1), m2sr(1), ccr2jr(1), csp2jr(1)

DIAGNOSTICS

Some erroneous monitor code will cause errors from m2jr. These line numbers generally correspond to the ones in the .m file.

Other errors in monitor 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.m, line 12  x = y+2;
This is the line that immediately caused the error.