<?xml version="1.0" encoding="utf-8"?>

<!--

Written by Joey Hess

-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[]>

<refentry>
	<refentryinfo>
		<address>
			<email>id@joeyh.name</email>
		</address>
		<author>
			<firstname>Joey</firstname>
			<surname>Hess</surname>
		</author>
		<date>2009-07-02</date>
	</refentryinfo>

	<refmeta>
		<refentrytitle>parallel</refentrytitle>
		<manvolnum>1</manvolnum>
		<refmiscinfo class="manual">moreutils</refmiscinfo>
		<refmiscinfo class="source">moreutils</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>parallel</refname> 
		<refpurpose>run programs in parallel</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>parallel</command>
			<arg>options</arg>
			<arg>command</arg>
			<command>--</command>
			<arg>argument ...</arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>parallel</command>
			<arg>options</arg>
			<command>--</command>
			<arg>command ...</arg>
		</cmdsynopsis>
	</refsynopsisdiv>
	
	<refsect1>
		<title>DESCRIPTION</title>
		
		<para><command>parallel</command> runs the specified command,
		passing it a single one of the specified arguments. This is
		repeated for each argument. Jobs may be run in
		parallel. The default is to run one job per CPU.</para>

		<para>If no command is specified before the --,
		the commands after it are instead run in parallel.</para>

	</refsect1>
	
	<refsect1>
		<title>OPTIONS</title>
		
		<variablelist>
		
		<varlistentry>
			<term><option>-j maxjobs</option></term>
			<listitem>
				<para>Use to limit the number of jobs
				that are run at the same time.</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><option>-l maxload</option></term>
			<listitem>
				<para>Wait as needed to avoid starting
				new jobs when the system's load average
				is not below the specified limit.</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><option>-i</option></term>
			<listitem>
				<para>Normally the command is passed the
				argument at the end of its command line. With
				this option, any instances of "{}" in
				the command are replaced with the argument.</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><option>-n</option></term>
			<listitem>
				<para>Number of arguments to pass to a
				command at a time. Default is 1.
				Incompatible with -i</para>
			</listitem>
		</varlistentry>
		
		</variablelist>
		
	</refsect1>

	<refsect1>
		<title>EXAMPLE</title>
		
	<para>
		<command>parallel sh -c "echo hi; sleep 2; echo bye" -- 1 2 3</command>
	</para>

	<para>This runs three subshells that each print a message, delay,
		and print another message. If your system has multiple
		CPUs, parallel will run some of the jobs in parallel,
		which should be clear from the order the messages are
		output.
	</para>
		
	<para>
		<command>parallel -j 3 ufraw -o processed -- *.NEF</command>
	</para>

	<para>This runs three ufraw processes at the same time until
	all of the NEF files have been processed.
	</para>
	
	<para>
		<command>parallel -j 3 -- ls df "echo hi"</command>
	</para>

	<para>This runs three independent commands in parallel.</para>

	</refsect1>

	<refsect1>
		<title>EXIT STATUS</title>


	<para>Its exit status is the combination of the exit statuses of each
	command ran, ORed together. (Thus, if any one command
	exits nonzero, <command>parallel</command> as a whole will exit nonzero.)</para>
		
	</refsect1>

	<refsect1>
		<title>NOTES</title>

	<para>
		All output to stdout and stderr is serialised through a
		corresponding internal pipe, in order to prevent annoying
		concurrent output behaviour.  Note that serialisation is not
		done on any other file descriptors and file position based
		access to a nonstandard file descriptor might have unexpected
		results.
	</para>

	</refsect1>
	
	<refsect1>
		<title>AUTHOR</title>
		<para>
			Tollef Fog Heen
		</para>
	</refsect1>

</refentry>
