mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 08:58:56 +00:00
deletions
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328162 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Joe Watkins
parent
15cb1d089e
commit
ee206bb21c
6 changed files with 0 additions and 567 deletions
|
|
@ -1,28 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<appendix xml:id="pthreads.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.constants;
|
||||
&no.constants;
|
||||
</appendix>
|
||||
|
||||
<!-- 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
|
||||
-->
|
||||
|
|
@ -1,294 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision: 327532 $ -->
|
||||
|
||||
<chapter xml:id="pthreads.tutorials" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.examples;
|
||||
|
||||
<section role="examples">
|
||||
<para>This HelloWorld example demonstrates how simple it is to define and execute Threads in PHP applications.</para>
|
||||
<example>
|
||||
<title>Hello World Example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class HelloWorld extends Thread {
|
||||
public function __construct($world) {
|
||||
$this->world = $world;
|
||||
}
|
||||
|
||||
public function run() {
|
||||
return sprintf("Hello %s", $this->world);
|
||||
}
|
||||
}
|
||||
|
||||
$thread = new HelloWorld("World");
|
||||
|
||||
if ($thread->start()) {
|
||||
printf("Thread #%lu says: %s\n", $thread->getThreadId(), $thread->join());
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</section>
|
||||
|
||||
<section role="examples">
|
||||
<para>
|
||||
The purpose of PHP is to generate content, having Threading in the toolbox
|
||||
makes more content available. But content is a relative subject, for this
|
||||
reason good control is needed over when a Thread is allowed to execute,
|
||||
or indeed, forced to wait.
|
||||
</para>
|
||||
<para>
|
||||
For example, a meta search engine may have to carry out the following:
|
||||
</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Initiate a search with primary source of data
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Log results of API usage for statistical analysis
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Cache results to limit external API usage
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Query local databases to generate page content - recent searches etc
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Log results of local database usage, HTTP usage, cache usage and
|
||||
possibly fall back to secondary source and goto 2;
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Generate content ( HTML ) from API output, xml/json etc
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Send content to client
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<para>
|
||||
In a multi-threaded design, the Thread delegated Task 2 cannot possibly run
|
||||
until Thread 1 has returned a result.
|
||||
</para>
|
||||
<para>
|
||||
In an extreme design, where each Task is allocated a Thread, Threads 2,3,4,5
|
||||
and even 6 can all be run concurrently, but they all depend on Thread 1
|
||||
returning content.
|
||||
</para>
|
||||
<para>
|
||||
pthreads includes an easy to use way to synchronize when Threads are allowed
|
||||
to execute, or forced to wait, to allow flexible, powerful multi-threading
|
||||
whether being used for a Search Engine or Administration ( ie. cron jobs ).
|
||||
</para>
|
||||
<example>
|
||||
<title>Synchronization</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class Task1 extends Thread {
|
||||
public function __construct($params) {
|
||||
$this->params = $params;
|
||||
}
|
||||
|
||||
/* ... */
|
||||
|
||||
public function run() {
|
||||
|
||||
/* do some admin possibly here, maybe lookup local caches, check if the client is googlebot etc */
|
||||
if ($this->ensureAvailabiilty()) {
|
||||
$this->notify();
|
||||
return $this->resultSet();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
class Task2 extends Thread {
|
||||
public function __construct($task1, $params) {
|
||||
$this->task1 = $task1;
|
||||
$this->params = $params;
|
||||
}
|
||||
|
||||
/* ... */
|
||||
|
||||
public function run(){
|
||||
$task1 = Thread::getThread($this->task1);
|
||||
if ($task1->wait()) {
|
||||
$this->createLogs();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$tasks = array();
|
||||
$tasks[0] = new Task1($_POST);
|
||||
$tasks[1] = new Task2($tasks[0]->getThreadId(), $_POST);
|
||||
/* ... */
|
||||
|
||||
foreach ($tasks as $id => $task) {
|
||||
$task->start();
|
||||
}
|
||||
|
||||
/* ... */
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
<para>
|
||||
Using the wait/notify mechanism included in pthreads hides the complexity of
|
||||
using Mutex and Condition Variables to synchronize Threads, greatly simplifies
|
||||
readability and more importantly maintainability of an idea or implementation.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section role="examples">
|
||||
<para>
|
||||
pthreads allows direct access to ( a subset of ) both of these features.
|
||||
The programmer should take care to destroy Mutex and Condition Variable
|
||||
handles that are no longer required for their logic.
|
||||
</para>
|
||||
<para>
|
||||
Mutex and Condition Variables are not destroyed on behalf of the programmer
|
||||
like other resources in PHP, as this would limit their usefulness in the
|
||||
context of multi-threading in SAPI environments.
|
||||
</para>
|
||||
<para>
|
||||
They are easily stored and passed around as they are represented as long numbers.
|
||||
Mutex and Condition Variables persist once allocated until they are explicitly
|
||||
destroyed.
|
||||
</para>
|
||||
<example>
|
||||
<title>Mutex and Condition Variables</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
/* ... */
|
||||
if (Cond::broadcast($finished)) {
|
||||
Cond::destroy($finished);
|
||||
Mutex::destroy($signals);
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
<para>
|
||||
The snippet above shows a PHP script sending it's final broadcast to the Threads
|
||||
it has created and cleaning up the Condition Variable it created and used for
|
||||
the broadcast. Other Threads that were waiting for a signal on $finished were
|
||||
using $signals - waiting for a signal always requires a Mutex - and as the
|
||||
Condition Variable is no longer valid, the accompanying Mutex is also destroyed.
|
||||
</para>
|
||||
<para>
|
||||
<warning>
|
||||
<para>
|
||||
Before the programmer attempts to use Condition Variables they should have
|
||||
knowledge of "Spurious Wakeups" as allowed for in the Posix Threads
|
||||
specification upon which pthreads is built.
|
||||
</para>
|
||||
<para>
|
||||
A brief explanation of the problem is as follows:
|
||||
</para>
|
||||
<para>
|
||||
A call to Cond::wait may return before the Condition Variable receives a
|
||||
legitimate signal as a result of another context calling Cond::signal
|
||||
or Cond::broadcast. Because of this behavior, a call to wait for a
|
||||
signal on a Condition Variable must check a predicate (usually a boolean
|
||||
value) upon returning from the call to Cond::wait. This eliminates the
|
||||
risk of Spurious Wakeups.
|
||||
</para>
|
||||
</warning>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section role="examples">
|
||||
<title>Thread Members</title>
|
||||
<para>
|
||||
The members of a Thread can be of any type that PHP supports the serialization
|
||||
of, including programmer declared classes.
|
||||
</para>
|
||||
<para>
|
||||
In the case where a Thread contains members that are of a programmer declared
|
||||
type (class), the programmer must include the declaration using Thread::__prepare
|
||||
magic method.
|
||||
</para>
|
||||
<para>
|
||||
Thread::__prepare method is executed by pthreads in the newly created context,
|
||||
before the newly created context executes Thread::run. This results in correct
|
||||
deserialization of the programmer declared type in the new context.
|
||||
</para>
|
||||
<example>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class ExampleThread extends Thread {
|
||||
public function __prepare(){
|
||||
require_once("/path/to/inc.php");
|
||||
}
|
||||
|
||||
public function __construct($myType){
|
||||
$this->myType = $myType;
|
||||
}
|
||||
|
||||
public function run(){
|
||||
if (method_exists($this->myType, "myMethod")) {
|
||||
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
require_once("/path/to/inc.php");
|
||||
/* ... */
|
||||
|
||||
$my = new Inc();
|
||||
/* ... */
|
||||
|
||||
$example = new ExampleThread($my);
|
||||
if ($example->start()) {
|
||||
/* ... */
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
<para>
|
||||
In the example above, /path/to/inc.php declares a class, as defined by the
|
||||
programmer. The programmer includes the declaration in the global scope
|
||||
before passing an instance of the object to an instance of ExampleThread.
|
||||
The instance of ExampleThread is able to manipulate the object and execute
|
||||
member functions having included the declaration using __prepare magic.
|
||||
</para>
|
||||
</section>
|
||||
</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
|
||||
-->
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<phpdoc:classref xml:id="class.importedthread" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<title>The ImportedThread class</title>
|
||||
<titleabbrev>ImportedThread</titleabbrev>
|
||||
|
||||
<partintro>
|
||||
|
||||
<!-- {{{ ImportedThread intro -->
|
||||
<section xml:id="importedthread.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
An ImportedThread is returned by a call to Thread::getThread.
|
||||
This provides any Thread created by pthreads, in any context, being executed in the same instance of PHP, the ability to synchronize with any Thread including collect it's output.
|
||||
</para>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
||||
<section xml:id="importedthread.synopsis">
|
||||
&reftitle.classsynopsis;
|
||||
|
||||
<!-- {{{ Synopsis -->
|
||||
<classsynopsis>
|
||||
<ooclass><classname>ImportedThread</classname></ooclass>
|
||||
|
||||
<!-- {{{ Class synopsis -->
|
||||
<classsynopsisinfo>
|
||||
<ooclass>
|
||||
<classname>ImportedThread</classname>
|
||||
</ooclass>
|
||||
</classsynopsisinfo>
|
||||
<!-- }}} -->
|
||||
|
||||
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
|
||||
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.importedthread')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
|
||||
</classsynopsis>
|
||||
<!-- }}} -->
|
||||
|
||||
</section>
|
||||
|
||||
</partintro>
|
||||
|
||||
&reference.pthreads.entities.importedthread;
|
||||
|
||||
</phpdoc:classref>
|
||||
|
||||
<!-- 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
|
||||
-->
|
||||
|
|
@ -1,55 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="thread.isbusy" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>Thread::isBusy</refname>
|
||||
<refpurpose>Tell if a Thread is busy executing</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>final</modifier> <modifier>public</modifier> <type>boolean</type><methodname>Thread::isBusy</methodname>
|
||||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Tell if the referenced Thread is busy executing.
|
||||
A call to <function>Thread::join</function> on a busy Thread could result in significant blocking.
|
||||
A Thread being used as a Worker will always appear busy until a call to <function>Thread::join</function> on the Worker is made.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
&no.function.parameters;
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>A boolean indication of state.</para>
|
||||
</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
|
||||
-->
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="thread.stack" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>Thread::stack</refname>
|
||||
<refpurpose>Push work onto the stack for execution by the referenced Thread</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>Thread::stack</methodname>
|
||||
<methodparam><type>Object</type><parameter>work</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Pushing work onto the stack of an executing Thread automatically turns that Thread into a Worker.
|
||||
A Worker Thread will automatically pop work off the stack and execute the items run method.
|
||||
A Worker Thread is available until a call to <function>Thread::join</function> is recieved.
|
||||
The return value of the run method of an executed item is ignored, until the last execution on the stack.
|
||||
The last item on the stack has the return value of run available to the caller of <function>Thread::join</function> on the Worker Thread.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>work</parameter></term>
|
||||
<listitem>
|
||||
<para>An item of the same type as the referenced Thread</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>The size of stack after work was added.</para>
|
||||
</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
|
||||
-->
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="thread.unstack" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>Thread::unstack</refname>
|
||||
<refpurpose>Remove items from the referenced Threads stack.</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>Thread::unstack</methodname>
|
||||
<methodparam choice="opt"><type>Object</type><parameter>work</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>Remove an item, or all items if no parameters are present from the referenced Threads stack.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>work</parameter></term>
|
||||
<listitem>
|
||||
<para>Should be an object previous used as the parameter to <function>Thread::stack</function></para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>The size of the stack after work was removed.</para>
|
||||
</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
|
||||
-->
|
||||
Loading…
Reference in a new issue