diff --git a/reference/pthreads/constants.xml b/reference/pthreads/constants.xml deleted file mode 100644 index e8ce507d66..0000000000 --- a/reference/pthreads/constants.xml +++ /dev/null @@ -1,28 +0,0 @@ - - - - - &reftitle.constants; - &no.constants; - - - diff --git a/reference/pthreads/examples.xml b/reference/pthreads/examples.xml deleted file mode 100644 index 2d0d8518ff..0000000000 --- a/reference/pthreads/examples.xml +++ /dev/null @@ -1,294 +0,0 @@ - - - - - &reftitle.examples; - -
- This HelloWorld example demonstrates how simple it is to define and execute Threads in PHP applications. - - Hello World Example - -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()); -} -?> -]]> - - -
- -
- - 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. - - - For example, a meta search engine may have to carry out the following: - - - - - Initiate a search with primary source of data - - - - - Log results of API usage for statistical analysis - - - - - Cache results to limit external API usage - - - - - Query local databases to generate page content - recent searches etc - - - - - Log results of local database usage, HTTP usage, cache usage and - possibly fall back to secondary source and goto 2; - - - - - Generate content ( HTML ) from API output, xml/json etc - - - - - Send content to client - - - - - In a multi-threaded design, the Thread delegated Task 2 cannot possibly run - until Thread 1 has returned a result. - - - 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. - - - 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 ). - - - Synchronization - -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(); -} - -/* ... */ -?> -]]> - - - - 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. - -
- -
- - 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. - - - 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. - - - 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. - - - Mutex and Condition Variables - - -]]> - - - - 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. - - - - - 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. - - - A brief explanation of the problem is as follows: - - - 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. - - - -
- -
- Thread Members - - The members of a Thread can be of any type that PHP supports the serialization - of, including programmer declared classes. - - - 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. - - - 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. - - - -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()) { - /* ... */ -} -?> -]]> - - - - 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. - -
- - - diff --git a/reference/pthreads/importedthread.xml b/reference/pthreads/importedthread.xml deleted file mode 100644 index 98ab86f06f..0000000000 --- a/reference/pthreads/importedthread.xml +++ /dev/null @@ -1,68 +0,0 @@ - - - - - - The ImportedThread class - ImportedThread - - - - -
- &reftitle.intro; - - 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. - -
- - -
- &reftitle.classsynopsis; - - - - ImportedThread - - - - - ImportedThread - - - - - &Methods; - - - - -
- - - - &reference.pthreads.entities.importedthread; - - - - diff --git a/reference/pthreads/thread/isbusy.xml b/reference/pthreads/thread/isbusy.xml deleted file mode 100644 index cc0078508a..0000000000 --- a/reference/pthreads/thread/isbusy.xml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - Thread::isBusy - Tell if a Thread is busy executing - - - - &reftitle.description; - - final public booleanThread::isBusy - - - - Tell if the referenced Thread is busy executing. - A call to Thread::join on a busy Thread could result in significant blocking. - A Thread being used as a Worker will always appear busy until a call to Thread::join on the Worker is made. - - - - - &reftitle.parameters; - &no.function.parameters; - - - - &reftitle.returnvalues; - A boolean indication of state. - - - - - - diff --git a/reference/pthreads/thread/stack.xml b/reference/pthreads/thread/stack.xml deleted file mode 100644 index b5e972b21b..0000000000 --- a/reference/pthreads/thread/stack.xml +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - Thread::stack - Push work onto the stack for execution by the referenced Thread - - - - &reftitle.description; - - final public intThread::stack - Objectwork - - - 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 Thread::join 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 Thread::join on the Worker Thread. - - - - - &reftitle.parameters; - - - work - - An item of the same type as the referenced Thread - - - - - - - &reftitle.returnvalues; - The size of stack after work was added. - - - - - - diff --git a/reference/pthreads/thread/unstack.xml b/reference/pthreads/thread/unstack.xml deleted file mode 100644 index aca4e80eec..0000000000 --- a/reference/pthreads/thread/unstack.xml +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - Thread::unstack - Remove items from the referenced Threads stack. - - - - &reftitle.description; - - final public intThread::unstack - Objectwork - - Remove an item, or all items if no parameters are present from the referenced Threads stack. - - - - &reftitle.parameters; - - - work - - Should be an object previous used as the parameter to Thread::stack - - - - - - - &reftitle.returnvalues; - The size of the stack after work was removed. - - - - - -