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

<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="parallel-runtime.run">

<refnamediv>

<refname>parallel\Runtime::run</refname>

<refpurpose>Execution</refpurpose>

</refnamediv>

<refsect1 role="description" audience="execute">

&reftitle.description;

<methodsynopsis>

<modifier>public</modifier> <type class="union"><type>Future</type><type>null</type></type><methodname>parallel\Runtime::run</methodname>

<methodparam><type>Closure</type><parameter>task</parameter></methodparam>

</methodsynopsis>

<simpara>

Shall schedule <parameter>task</parameter> for execution in parallel.

</simpara>

<methodsynopsis>

<modifier>public</modifier> <type class="union"><type>Future</type><type>null</type></type><methodname>parallel\Runtime::run</methodname>

<methodparam><type>Closure</type><parameter>task</parameter></methodparam>

<methodparam><type>array</type><parameter>argv</parameter></methodparam>

</methodsynopsis>

<simpara>

Shall schedule <parameter>task</parameter> for execution in parallel, passing <parameter>argv</parameter> at execution time.

</simpara>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>task</parameter></term>

<listitem>

<simpara>

A <classname>Closure</classname> with specific characteristics.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>argv</parameter></term>

<listitem>

<simpara>

An <type>array</type> of arguments with specific characteristics to be passed to <parameter>task</parameter> at execution time.

</simpara>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="closure-characteristics">

<title>Task Characteristics</title>

<para>

Closures scheduled for parallel execution must not:

<simplelist>

<member>accept or return by reference</member>

<member>accept or return internal objects (see notes)</member>

<member>execute a limited set of instructions</member>

</simplelist>

</para>

<para>

Instructions prohibited in Closures intended for parallel execution are:

<simplelist>

<member>yield</member>

<member>use by-reference</member>

<member>declare class</member>

<member>declare named function</member>

</simplelist>

</para>

<note>

<simpara>

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

</simpara>

</note>

<note>

<simpara>

No instructions are prohibited in the files which the task may include.

</simpara>

</note>

</refsect1>

<refsect1 role="argv-characteristics">

<title>Arguments Characteristics</title>

<para>

Arguments must not:

<simplelist>

<member>contain references</member>

<member>contain resources</member>

<member>contain internal objects (see notes)</member>

</simplelist>

<note>

<simpara>

In the case of file stream resources, the resource will be cast to the file descriptor and passed as <type>int</type> where possible, this is unsupported on Windows.

</simpara>

</note>

</para>

</refsect1>

<refsect1 role="object-characteristics">

<title>Internal Objects Notes</title>

<simpara>

Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks the mechanics to do this (without serialization)

and so only objects that do not use a custom structure may be shared.

</simpara>

<simpara>

Some internal objects do not use a custom structure, for example <classname>parallel\Events\Event</classname> and so may be shared.

</simpara>

<simpara>

Closures are a special kind of internal object and support being copied by value, and so may be shared.

</simpara>

<simpara>

Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.

</simpara>

<warning>

<simpara>

A user class that extends an internal class may use a custom structure as defined by the internal class, in which case they cannot be copied by value safely,

and so may not be shared.

</simpara>

</warning>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<warning>

<simpara>

The return <type>parallel\Future</type> must not be ignored when the task contains a return or throw statement.

</simpara>

</warning>

</refsect1>

<refsect1 role="exceptions">

<title>Exceptions</title>

<warning>

<simpara>

Shall throw <type>parallel\Runtime\Error\Closed</type> if <type>parallel\Runtime</type> was closed.

</simpara>

</warning>

<warning>

<simpara>

Shall throw <type>parallel\Runtime\Error\IllegalFunction</type> if <parameter>task</parameter> is a closure created from an internal function.

</simpara>

</warning>

<warning>

<simpara>

Shall throw <type>parallel\Runtime\Error\IllegalInstruction</type> if <parameter>task</parameter> contains illegal instructions.

</simpara>

</warning>

<warning>

<simpara>

Shall throw <type>parallel\Runtime\Error\IllegalParameter</type> if <parameter>task</parameter> accepts or <parameter>argv</parameter> contains illegal variables.

</simpara>

</warning>

<warning>

<simpara>

Shall throw <type>parallel\Runtime\Error\IllegalReturn</type> if <parameter>task</parameter> returns illegally.

</simpara>

</warning>

</refsect1>

</refentry>