sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

parallel updates

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@347449 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Joe Watkins 2019-05-20 08:29:22 +00:00
parent 107819d757
commit c636cca282
8 changed files with 316 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
reference/parallel/book.xml
View file

@ -2,8 +2,8 @@
<!-- $Revision$ -->
<book xml:id="book.parallel" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Parallel</title>
<titleabbrev>Parallel</titleabbrev>
<title>parallel</title>
<titleabbrev>parallel</titleabbrev>
<preface xml:id="intro.parallel">
&reftitle.intro;
@ -25,6 +25,13 @@
A <classname>parallel\Runtime</classname> has a FIFO schedule, tasks will be executed in the order that they are scheduled.
</para>
</simplesect>
<simplesect>
<title>Functional API</title>
<para>
parallel implements a functional, higher level API on top of <classname>parallel\Runtime</classname> that provides a single function entry point to executing parallel code
with automatic scheduling: <function>parallel\run</function>.
</para>
</simplesect>
<simplesect>
<title>Task</title>
<para>
@ -80,9 +87,17 @@
describing the operations that have occured.
</para>
</simplesect>
<simplesect role="seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="philosophy.parallel" /></member>
</simplelist>
</simplesect>
</preface>
&reference.parallel.setup;
&reference.parallel.philosophy;
&reference.parallel.functional;
&reference.parallel.parallel.runtime;
&reference.parallel.parallel.future;
&reference.parallel.parallel.channel;

49
reference/parallel/functional.xml Normal file
View file

@ -0,0 +1,49 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 344522 $ -->
<reference xml:id="functional.parallel" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Functional API</title>
<partintro>
<para>
The <classname>parallel\Runtime</classname> API provides a great degree of control to the power PHP programmer, and those intimately familiar with writing applications that use
parallel concurrency.
</para>
<para>
The functional API provides less control in exchange for the ability to make decisions for the programmer:
<itemizedlist>
<listitem>
<para>all executing runtimes are bootstrapped identically</para>
</listitem>
<listitem>
<para>scheduling is determined by the API, not the programmer</para>
</listitem>
</itemizedlist>
<function>parallel\run</function> provides the guarantee that the task will begin to execute in parallel as soon as allowed by hardware and operating system constraints, without
needlessly creating runtimes. For most applications the functional API should be preferred.
</para>
</partintro>
&reference.parallel.functions.parallel.bootstrap;
&reference.parallel.functions.parallel.run;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

62
reference/parallel/functions/parallel.bootstrap.xml Normal file
View file

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 345674 $ -->
<refentry xml:id="parallel.bootstrap" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<refnamediv>
<refname>parallel\bootstrap</refname>
<refpurpose>Bootstrapping</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>parallel\bootstrap</methodname>
<methodparam><type>string</type><parameter>file</parameter></methodparam>
</methodsynopsis>
<para>
Shall use the provided <parameter>file</parameter> to bootstrap all runtimes created for automatic scheduling via <function>parallel\run</function>.
</para>
</refsect1>
<refsect1 role="exceptions">
<title>Exceptions</title>
<warning>
<para>
Shall throw <type>\parallel\Runtime\Error\Bootstrap</type> if previously called for this process.
</para>
</warning>
<warning>
<para>
Shall throw <type>\parallel\Runtime\Error\Bootstrap</type> if called after <function>parallel\run</function>.
</para>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="parallel-runtime.run" /></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

77
reference/parallel/functions/parallel.run.xml Normal file
View file

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 345674 $ -->
<refentry xml:id="parallel.run" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<refnamediv>
<refname>parallel\run</refname>
<refpurpose>Execution</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>?Future</type><methodname>parallel\run</methodname>
<methodparam><type>Closure</type><parameter>task</parameter></methodparam>
</methodsynopsis>
<para>
Shall schedule <parameter>task</parameter> for execution in parallel.
</para>
<methodsynopsis>
<type>?Future</type><methodname>parallel\run</methodname>
<methodparam><type>Closure</type><parameter>task</parameter></methodparam>
<methodparam><type>array</type><parameter>argv</parameter></methodparam>
</methodsynopsis>
<para>
Shall schedule <parameter>task</parameter> for execution in parallel, passing <parameter>argv</parameter> at execution time.
</para>
</refsect1>
<refsect1 role="scheduling-characteristics">
<title>Automatic Scheduling</title>
<para>
If a <classname>\parallel\Runtime</classname> internally created and cached by a previous call to <function>parallel\run</function> is idle,
it will be used to execute the task. If no <classname>\parallel\Runtime</classname> is idle parallel will create and cache a
<classname>\parallel\Runtime</classname>.
</para>
<note>
<para>
<classname>\parallel\Runtime</classname> objects created by the programmer are not used for automatic scheduling.
</para>
</note>
</refsect1>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='parameters'])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='closure-characteristics'])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='argv-characteristics'])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='object-characteristics'])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='returnvalues'])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('parallel-runtime.run')/db:refsect1[@role='exceptions'])" />
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="parallel-runtime.run" /></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

29
reference/parallel/parallel/runtime/run.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="parallel-runtime.run" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>parallel\Runtime::run</refname>
<refpurpose>Parallel Execution</refpurpose>
<refpurpose>Execution</refpurpose>
</refnamediv>
<refsect1 role="description" audience="execute">
@ -55,7 +55,7 @@
Closures scheduled for parallel execution must not:
<simplelist>
<member>accept or return by reference</member>
<member>accept or return objects (that are not closures)</member>
<member>accept or return internal objects (see notes)</member>
<member>execute a limited set of instructions</member>
</simplelist>
</para>
@ -86,8 +86,8 @@
Arguments must not:
<simplelist>
<member>contain references</member>
<member>contain objects (that are not closures)</member>
<member>contain resources</member>
<member>contain internal objects (see notes)</member>
</simplelist>
<note>
<para>
@ -97,6 +97,29 @@
</para>
</refsect1>
<refsect1 role="object-characteristics">
<title>Internal Objects Notes</title>
<para>
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.
</para>
<para>
Some internal objects do not use a custom structure, for example <classname>parallel\Events\Event</classname> and so may be shared.
</para>
<para>
Closures are a special kind of internal object and support being copied by value, and so may be shared.
</para>
<para>
Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.
</para>
<warning>
<para>
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.
</para>
</warning>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<warning>

77
reference/parallel/philosophy.xml Normal file
View file

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 344522 $ -->
<chapter xml:id="philosophy.parallel" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Philosophy</title>
<para>
This section contains philosohpies important to writing parallel code and some details about the internal implementation of parallel.
</para>
<simplesect role="sharing">
<title>Do not communicate by sharing memory; instead, share memory by communicating.</title>
<para>
This philosophy which is embraced by parallel has its origins in Go, one of the most widely admired if not used platforms for writing parallel code at the moment.
Go programmers have to work hard to live up to this ideal: PHP and parallel do all the hard work for the programmer, and by default.
</para>
<para>
In conventional threading models found in other languages, generally threads are communicating with one another through nothing more than by virtue of the fact that
they operate in the same address space.
The programmer must deploy mutual exclusion, condition variables, and other low level threading or synchronization primitives in order to ensure proper communication
of state and consistency.
</para>
<para>
When the conventional model is inversed, it means that threads only share memory as a result of communication (a variable is passed over a Channel for example).
</para>
<para>
When parallel passes a variable from one thread to another by any means - Task arguments, return via Future, and Channels - it is passed by value.
In all but the case of unbuffered channels, the variable is also buffered so that it may not change (or be destroyed) before it is used in whichever thread the variable
is being passed to. An unbuffered read over a channel is the only instance in which a thread directly reads memory allocated by another thread, it can do so safely because
the thread that owns the memory is waiting for the read to complete before it can continue to manipulate it, and the thread that does not own the memory reads by value. When
both threads continue, they are no longer sharing memory.
</para>
<para>
This makes writing and reasoning about parallel code much easier than the conventional model of threading. It means the programmer does not need to consider that threads
may be manipulating data concurrently, because that is not possible.
</para>
<para>
This also makes PHP the perfect platform for implementing a parallel concurrency API based on CSP (message passing over channels), because PHP itself is shared nothing -
PHP threads operate in their own virtual address space by default, and so may only share memory by communicating.
</para>
</simplesect>
<simplesect role="owning">
<title>Data should have a definitive single owner</title>
<para>
When approaching the CSP model for the first time, a programmer versed in the traditional model of threading may find themselves looking for concurrent data structures,
because that is what they are used too: they pass around shared objects for manipulation.
</para>
<para>
When it comes to the CSP model, there is no need for data structures to be shared by many tasks, and indeed, it is simpler if they are not. The data should be owned
by a single task, changes to (or operations on) that data structure should be communicated over channels and performed by the owner of the data, the success, failure,
or result (state) of the change (or operation) being communicated back.
</para>
<para>
Once again the share nothing nature of PHP and copy by value nature of parallel helps the programmer to achieve this goal, no data will be shared by accident,
only ever as a result of communication.
</para>
</simplesect>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

10
reference/parallel/setup.xml
View file

@ -2,9 +2,9 @@
<!-- $Revision$ -->
<chapter xml:id="parallel.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<title>Installation</title>
<section xml:id="parallel.requirements">
<simplesect xml:id="parallel.requirements">
&reftitle.required;
<para>
parallel requires a build of PHP with ZTS (Zend Thread Safety) enabled ( --enable-maintainer-zts or --enable-zts on Windows )
@ -17,9 +17,9 @@
<para>
parallel should build anywhere there is a working Posix Threads header (pthread.h) and ZTS build of PHP, including Windows (using the pthread-w32 project from redhat).
</para>
</section>
</simplesect>
<section xml:id="parallel.installation">
<simplesect xml:id="parallel.installation">
&reftitle.install;
<para>
parallel releases are hosted by PECL and the source code by
@ -35,7 +35,7 @@
Windows users need to take the additional step of adding pthreadVC2.dll (distributed with Windows releases) to their <envar>PATH</envar>.
</para>
</caution>
</section>
</simplesect>
</chapter>

3
reference/parallel/versions.xml
View file

@ -7,6 +7,9 @@
<versions>
<!-- Classes and Methods -->
<function name='parallel\bootstrap' from='1.0.0'/>
<function name='parallel\run' from='1.0.0'/>
<function name='parallel\runtime' from='0.8.0'/>
<function name='parallel\runtime::__construct' from='0.8.0'/>
<function name='parallel\runtime::run' from='0.8.0'/>