diff --git a/reference/pthreads/cond/broadcast.xml b/reference/pthreads/cond/broadcast.xml index 7e585883fd..57d4f63415 100644 --- a/reference/pthreads/cond/broadcast.xml +++ b/reference/pthreads/cond/broadcast.xml @@ -16,8 +16,8 @@ boolean Cond::broadcast - long - condition + long + condition Broadcast to all Threads blocking on a call to Cond::wait. @@ -38,7 +38,7 @@ &reftitle.returnvalues; - A boolean indication of success. + A boolean indication of success. diff --git a/reference/pthreads/cond/destroy.xml b/reference/pthreads/cond/destroy.xml index 88acb66f4c..d316f22b1a 100644 --- a/reference/pthreads/cond/destroy.xml +++ b/reference/pthreads/cond/destroy.xml @@ -16,8 +16,8 @@ boolean Cond::destroy - long - condition + long + condition diff --git a/reference/pthreads/cond/signal.xml b/reference/pthreads/cond/signal.xml index e3572e6281..a37ecd6c59 100644 --- a/reference/pthreads/cond/signal.xml +++ b/reference/pthreads/cond/signal.xml @@ -21,7 +21,7 @@ - + diff --git a/reference/pthreads/examples.xml b/reference/pthreads/examples.xml index 62916a100f..024cd130ad 100644 --- a/reference/pthreads/examples.xml +++ b/reference/pthreads/examples.xml @@ -11,73 +11,73 @@ world = $world; - } - - public function run(){ - return sprintf("Hello %s", $this->world); - } + 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()); + printf("Thread #%lu says: %s\n", $thread->getThreadId(), $thread->join()); } ?> - ]]> + ]]>
- Synchronization - 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 databse 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 wether being used for a Search Engine or Administration ( ie. cron jobs ). - Synchronization + 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 databse 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 wether being used for a Search Engine or Administration ( ie. cron jobs ). + 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(); - } - } + 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(); - } - } + 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(); @@ -87,70 +87,70 @@ /* ... */ foreach ($tasks as $id => $task) { - $task->start(); + $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. + ]]> + 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.
- - Mutex and Condition Variables - 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 + 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. + - ]]> - + ]]> + 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. - + + + 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 exaplanation of the problem is as follows: - - + + A call to Cond::wait may return before the Condition Variable recieves a legitimate signal as a result of another context calling Cond::signal or Cond::broadcast. Because of this behaviour, 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. - + 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")) { - - } - } + 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"); /* ... */ @@ -158,15 +158,15 @@ /* ... */ $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/join.xml b/reference/pthreads/importedthread/join.xml index 21263eb03c..a7152b11da 100644 --- a/reference/pthreads/importedthread/join.xml +++ b/reference/pthreads/importedthread/join.xml @@ -27,7 +27,7 @@ &reftitle.returnvalues; - + diff --git a/reference/pthreads/mutex/create.xml b/reference/pthreads/mutex/create.xml index 6cbf55d5a7..22208e91d7 100644 --- a/reference/pthreads/mutex/create.xml +++ b/reference/pthreads/mutex/create.xml @@ -16,8 +16,8 @@ long Mutex::create - boolean - lock + boolean + lock Create, and optionally lock a new Mutex for the caller diff --git a/reference/pthreads/mutex/destroy.xml b/reference/pthreads/mutex/destroy.xml index 091903ac27..ab82173505 100644 --- a/reference/pthreads/mutex/destroy.xml +++ b/reference/pthreads/mutex/destroy.xml @@ -10,15 +10,15 @@ &reftitle.description; - final - public - static - boolean - Mutex::destroy - - long - mutex - + final + public + static + boolean + Mutex::destroy + + long + mutex + Destroying Mutex handles must be carried out explicitly by the programmer when they are finished with the Mutex handle. diff --git a/reference/pthreads/mutex/lock.xml b/reference/pthreads/mutex/lock.xml index ba6e725ea8..dbb1d29cdf 100644 --- a/reference/pthreads/mutex/lock.xml +++ b/reference/pthreads/mutex/lock.xml @@ -16,8 +16,8 @@ boolean Mutex::lock - long - mutex + long + mutex Attempt to lock the Mutex for the caller. diff --git a/reference/pthreads/mutex/trylock.xml b/reference/pthreads/mutex/trylock.xml index c640d66f75..8662032214 100644 --- a/reference/pthreads/mutex/trylock.xml +++ b/reference/pthreads/mutex/trylock.xml @@ -16,8 +16,8 @@ boolean Mutex::trylock - long - mutex + long + mutex Attempt to lock the Mutex for the caller without blocking if the Mutex is owned (locked) by another Thread. @@ -38,7 +38,7 @@ &reftitle.returnvalues; - A boolean indication of success. + A boolean indication of success. diff --git a/reference/pthreads/mutex/unlock.xml b/reference/pthreads/mutex/unlock.xml index e88fc9754f..3d610e765e 100644 --- a/reference/pthreads/mutex/unlock.xml +++ b/reference/pthreads/mutex/unlock.xml @@ -16,12 +16,12 @@ boolean Mutex::unlock - long - mutex - + long + mutex + - boolean - destroy + boolean + destroy diff --git a/reference/pthreads/thread/join.xml b/reference/pthreads/thread/join.xml index 2a28080ccd..0f24255d58 100644 --- a/reference/pthreads/thread/join.xml +++ b/reference/pthreads/thread/join.xml @@ -27,7 +27,7 @@ &reftitle.returnvalues; - + diff --git a/reference/pthreads/thread/run.xml b/reference/pthreads/thread/run.xml index 2e130027af..885b60af9f 100644 --- a/reference/pthreads/thread/run.xml +++ b/reference/pthreads/thread/run.xml @@ -28,7 +28,7 @@ &reftitle.returnvalues; - + diff --git a/reference/pthreads/thread/start.xml b/reference/pthreads/thread/start.xml index 96bc2bda19..cccbb8aea4 100644 --- a/reference/pthreads/thread/start.xml +++ b/reference/pthreads/thread/start.xml @@ -14,7 +14,7 @@ booleansynchronized - Start executing the referenced Thread, optionally synchronized with the caller. + Start executing the referenced Thread, optionally synchronized with the caller. @@ -35,7 +35,7 @@ &reftitle.returnvalues; - A boolean indication of success. + A boolean indication of success.