Files
2016-04-27 01:07:35 -04:00

392 lines
21 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (version 1.7.0_51) on Wed Apr 06 13:11:02 EDT 2016 -->
<title>pj2 (Parallel Java 2 Library Documentation)</title>
<meta name="date" content="2016-04-06">
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
</head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="pj2 (Parallel Java 2 Library Documentation)";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/pj2.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev Class</li>
<li><a href="ScalePlot.html" title="class in &lt;Unnamed&gt;"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="index.html?pj2.html" target="_top">Frames</a></li>
<li><a href="pj2.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<h2 title="Class pj2" class="title">Class pj2</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</a></li>
<li>
<ul class="inheritance">
<li>pj2</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>public class <span class="strong">pj2</span>
extends <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></pre>
<div class="block">Class pj2 is the PJ2 job and task launcher main program.
<P>
Usage: <TT>java pj2 [threads=<I>threads</I>] [schedule=<I>schedule</I>]
[chunk=<I>chunk</I>] [nodeName=<I>nodeName</I>] [cores=<I>cores</I>]
[gpus=<I>gpus</I>] [workers=<I>workers</I>]
[masterSchedule=<I>masterSchedule</I>] [masterChunk=<I>masterChunk</I>]
[tracker=<I>host</I>[:<I>port</I>]] [listen=<I>host</I>[:<I>port</I>]]
[debug=<I>message</I>[,<I>message</I>...]]
[jvmFlags=<I>flag</I>[,<I>flag</I>]] [jar=<I>file</I>]
[timelimit=<I>timelimit</I>] <I>jobOrTaskClass</I> [<I>arg</I> ...]</TT>
<P>
PJ2 is designed for writing two kinds of parallel programs: tightly coupled
single-node and loosely coupled multi-node.
<P>
<B>Tightly coupled single-node parallel programs.</B>
A tightly coupled single-node parallel program is intended to run on one
multicore node. The program consists of multiple threads that run in parallel
on separate cores. The threads communicate and coordinate by reading and
writing variables in shared memory.
<P>
This kind of PJ2 program is expressed as a subclass of class <a href="edu/rit/pj2/Task.html" title="class in edu.rit.pj2">Task</a>. The program is executed by running the <TT>pj2</TT>
program as follows:
<P>
<TT>$ java pj2 MainTask <I>arg</I> ...</TT>
<P>
The above command runs class MainTask, a subclass of class <a href="edu/rit/pj2/Task.html" title="class in edu.rit.pj2">Task</a>. Replace <TT>MainTask</TT> with the fully-qualified
class name of the desired task subclass. The <TT>pj2</TT> program creates an
instance of the task subclass, then calls that task's <a href="edu/rit/pj2/Task.html#main(java.lang.String[])"><code>main()</code></a> method, passing in an array of the
command line argument strings (zero or more). The <a href="edu/rit/pj2/Task.html#main(java.lang.String[])"><code>main()</code></a> method carries out the computation.
When the <a href="edu/rit/pj2/Task.html#main(java.lang.String[])"><code>main()</code></a> method returns, the
<TT>pj2</TT> program terminates.
<P>
The computation can contain sequential statements executed by a single
thread, interspersed with parallel statements executed by multiple threads.
Running on a multicore computer, the Java Virtual Machine (JVM) schedules
each thread on a separate core, thus executing the program in parallel.
<P>
<B>Loosely coupled multi-node parallel programs.</B>
A loosely coupled multi-node parallel program is intended to run on multiple
nodes. The nodes may be located in a cluster parallel computer, in a grid, or
in a cloud. The program consists of multiple <a href="edu/rit/pj2/Task.html" title="class in edu.rit.pj2">Task</a>s that run in parallel on separate nodes. The tasks coordinate and
communicate with each other by reading and writing <a href="edu/rit/pj2/Tuple.html" title="class in edu.rit.pj2">Tuple</a>s in <I>tuple space.</I> The tasks are intended to be
<I>coarse-grained,</I> meaning each task runs for minutes or hours, not
milliseconds. The tasks are intended to communicate <I>small to medium
amounts of data</I> via tuple space, not enormous quantities of data.
<P>
This kind of PJ2 program is expressed as a subclass of class <a href="edu/rit/pj2/Job.html" title="class in edu.rit.pj2">Job</a>. The program is executed by running the <TT>pj2</TT>
program as follows:
<P>
<TT>$ java pj2 jar=<I>file</I> MainJob <I>arg</I> ...</TT>
<P>
The above command runs class MainJob, a subclass of class <a href="edu/rit/pj2/Job.html" title="class in edu.rit.pj2">Job</a>. Replace <TT>MainJob</TT> with the fully-qualified class
name of the desired job subclass. The <TT>pj2</TT> program creates an
instance of the job subclass, then calls that job's <a href="edu/rit/pj2/Job.html#main(java.lang.String[])"><code>main()</code></a> method, passing in an array of the
command line argument strings (zero or more). The <a href="edu/rit/pj2/Job.html#main(java.lang.String[])"><code>main()</code></a> method defines <a href="edu/rit/pj2/Rule.html" title="class in edu.rit.pj2">Rule</a>s that specify which <a href="edu/rit/pj2/Task.html" title="class in edu.rit.pj2">Task</a>s are to be executed as part of the job. The <TT>pj2</TT> program
creates and executes those tasks, which carry out the job's computation. The
tasks may execute in the <TT>pj2</TT> program's process or on computational
nodes that are part of a cluster, grid, or cloud. When all the tasks have
finished executing, the <TT>pj2</TT> program terminates.
<P>
Running on a cluster, grid, or cloud, the program executes each task on a
separate node, thus executing the program in parallel. Each task receives
input tuples that are taken out of tuple space, performs computations, and
generates output tuples that are written into tuple space. Each task executes
independently of other tasks. All inter-task coordination and communication
goes through tuple space.
<P>
<B>Properties.</B>
Certain properties of the job or task can be specified on the <TT>pj2</TT>
command line by including the appropriate option before the job or task class
name. These override the default property values. The properties are:
<UL>
<P><LI>
<TT>threads</TT> specifies the number of threads that will execute a parallel
for loop. Specify <TT>threads=all</TT> to indicate that a parallel for loop
will be executed by as many threads as there are cores on the machine on
which the task is running. The default is <TT>threads=all</TT>. See the
<a href="edu/rit/pj2/Job.html#threads(int)"><code>Job.threads()</code></a> or <a href="edu/rit/pj2/Task.html#threads(int)"><code>Task.threads()</code></a> method for further information.
<P><LI>
<TT>schedule</TT> specifies how the iterations of a parallel for loop are
partitioned among the threads executing the parallel for loop. The default is
a fixed schedule. See the <a href="edu/rit/pj2/Job.html#schedule(edu.rit.pj2.Schedule)"><code>Job.schedule()</code></a> or <a href="edu/rit/pj2/Task.html#schedule(edu.rit.pj2.Schedule)"><code>Task.schedule()</code></a> method for
further information.
<P><LI>
<TT>chunk</TT> specifies how the iterations of a parallel for loop are
partitioned among the threads executing the parallel for loop. The
interpretation of the default <TT>chunk</TT> property depends on the
<TT>schedule</TT> property. See the <a href="edu/rit/pj2/Job.html#chunk(int)"><code>Job.chunk()</code></a> or <a href="edu/rit/pj2/Task.html#chunk(int)"><code>Task.chunk()</code></a> method for
further information.
<P><LI>
<TT>nodeName</TT> specifies the name of the node on which a task must run.
Specify <TT>nodeName=any</TT> to indicate that a task can run on any node.
The default is <TT>nodeName=any</TT>. See the <a href="edu/rit/pj2/Job.html#nodeName(java.lang.String)"><code>Job.nodeName()</code></a> or <a href="edu/rit/pj2/Task.html#nodeName(java.lang.String)"><code>Task.nodeName()</code></a> method for further
information.
<P><LI>
<TT>cores</TT> specifies the number of CPU cores a task requires. Specify
<TT>cores=all</TT> to indicate that a task requires all the CPU cores on the
node. The default is <TT>cores=all</TT>. See the <a href="edu/rit/pj2/Job.html#cores(int)"><code>Job.cores()</code></a> or <a href="edu/rit/pj2/Task.html#cores(int)"><code>Task.cores()</code></a> method for further information.
<P><LI>
<TT>gpus</TT> specifies the number of GPU accelerators a task requires. The
default is none (0). See the <a href="edu/rit/pj2/Job.html#gpus(int)"><code>Job.gpus()</code></a> or
<a href="edu/rit/pj2/Task.html#gpus(int)"><code>Task.gpus()</code></a> method for further
information.
<P><LI>
<TT>workers</TT> specifies the number of worker tasks that will execute a
master-worker cluster parallel for loop. The default is one worker task. See
the <a href="edu/rit/pj2/Job.html#workers(int)"><code>Job.workers()</code></a> method for further
information.
<P><LI>
<TT>masterSchedule</TT> specifies how the iterations of a master-worker
cluster parallel for loop are partitioned among the worker tasks executing
the parallel for loop. The default is a fixed schedule. See the <a href="edu/rit/pj2/Job.html#masterSchedule(edu.rit.pj2.Schedule)"><code>Job.masterSchedule()</code></a>
method for further information.
<P><LI>
<TT>masterChunk</TT> specifies how the iterations of a master-worker cluster
parallel for loop are partitioned among the worker tasks executing the
parallel for loop. The interpretation of the default <TT>masterChunk</TT>
property depends on the <TT>masterSchedule</TT> property. See the <a href="edu/rit/pj2/Job.html#masterChunk(int)"><code>Job.masterChunk()</code></a> method for further
information.
<P><LI>
<TT>tracker</TT> specifies the host and port at which the Tracker is
listening for connections from jobs. If <TT>tracker=none</TT> is specified,
the job will not connect to the Tracker. See the <a href="edu/rit/pj2/Job.html#trackerHost(java.lang.String)"><code>Job.trackerHost()</code></a> and <a href="edu/rit/pj2/Job.html#trackerPort(int)"><code>Job.trackerPort()</code></a> methods for further
information.
<P><LI>
<TT>listen</TT> specifies the host and port at which the job itself will
listen for connections from the nodes that will run the job's tasks. See the
<a href="edu/rit/pj2/Job.html#listenHost(java.lang.String)"><code>Job.listenHost()</code></a> and <a href="edu/rit/pj2/Job.html#listenPort(int)"><code>Job.listenPort()</code></a> methods for further
information.
<P><LI>
<TT>debug</TT> tells a job to print a certain debugging message or messages.
Multiple messages may be specified, separated by commas (no spaces). Specify
<TT>debug=all</TT> to turn on all debugging messages. Specify
<TT>debug=none</TT> to turn off all debugging messages. See the <a href="edu/rit/pj2/Job.html#debug(edu.rit.pj2.Debug...)"><code>Job.debug()</code></a> method for further
information.
<P><LI>
<TT>jvmFlags</TT> specifies one or more flags that are included on the
command lines of the JVMs that run each of the tasks in the job. Multiple
flags may be specified, separated by commas (no spaces). See the <a href="edu/rit/pj2/Job.html#jvmFlags(java.lang.String...)"><code>Job.jvmFlags()</code></a> method for further
information.
<P><LI>
<TT>jar</TT> specifies the Java archive (JAR) file that contains the class
files needed by a job and its tasks. For further information, see class
<a href="edu/rit/pj2/Job.html" title="class in edu.rit.pj2">Job</a>.
<P><LI>
<TT>timelimit</TT> specifies a time limit in seconds for the job. The default
is no time limit. See the <a href="edu/rit/pj2/Job.html#timeLimit(int)"><code>Job.timeLimit()</code></a> method for further information.
</UL>
<P>
<B>Abnormal termination.</B>
If code in a job or task throws an exception that propagates out of the
<TT>main()</TT> method, the <TT>pj2</TT> program prints an exception stack
trace and terminates.
<P>
Code in a job or task must <I>not</I> call the <TT>System.exit()</TT> method.
If a job or task needs to terminate itself, the job or task should throw an
exception that propagates out of every method without being caught, such as a
<a href="edu/rit/pj2/TerminateException.html" title="class in edu.rit.pj2">TerminateException</a> or any other
runtime exception. The exception's detail message can explain why the job or
task terminated. This exception propagates out of the <TT>main()</TT> method
and causes the <TT>pj2</TT> program to terminate.</div>
<dl><dt><span class="strong">See Also:</span></dt><dd><a href="edu/rit/pj2/package-summary.html"><code>edu.rit.pj2</code></a>,
<a href="edu/rit/pj2/Job.html" title="class in edu.rit.pj2"><code>Job</code></a>,
<a href="edu/rit/pj2/Task.html" title="class in edu.rit.pj2"><code>Task</code></a></dd></dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method_summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span>Methods</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static void</code></td>
<td class="colLast"><code><strong><a href="pj2.html#main(java.lang.String[])">main</a></strong>(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]&nbsp;args)</code>
<div class="block">PJ2 launcher main program.</div>
</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a name="methods_inherited_from_class_java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class&nbsp;java.lang.<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></h3>
<code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#clone()" title="class or interface in java.lang">clone</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang">equals</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#finalize()" title="class or interface in java.lang">finalize</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang">hashCode</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method_detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="main(java.lang.String[])">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>main</h4>
<pre>public static&nbsp;void&nbsp;main(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]&nbsp;args)</pre>
<div class="block">PJ2 launcher main program.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>args</code> - Property settings (optional), job or task class name, job's
or task's command line arguments (zero or more).</dd></dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/pj2.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev Class</li>
<li><a href="ScalePlot.html" title="class in &lt;Unnamed&gt;"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="index.html?pj2.html" target="_top">Frames</a></li>
<li><a href="pj2.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><FONT SIZE="-2">Copyright &copy; 2013&ndash;2016 by Alan Kaminsky. All rights reserved. Send comments to ark</FONT><FONT SIZE="1" COLOR="#FFFFFF">&shy;</FONT><FONT SIZE="-2">&#64;</FONT><FONT SIZE="1" COLOR="#FFFFFF">&shy;</FONT><FONT SIZE="-2">cs.rit.edu.</FONT></small></p>
</body>
</html>