diff --git a/reference/pthreads/book.xml b/reference/pthreads/book.xml
index 6cfb755b63..4c0412b9f1 100644
--- a/reference/pthreads/book.xml
+++ b/reference/pthreads/book.xml
@@ -8,17 +8,17 @@
&reftitle.intro;
- pthreads uses the well tested abilities of TSRM and PHP to
- provide compatible multi-threading capabilities.
+ pthreads uses the well tested abilities of TSRM and PHP to provide object oreintated multi-threading capabilities.
&reference.pthreads.setup;
- &reference.pthreads.constants;
- &reference.pthreads.examples;
&reference.pthreads.thread;
+ &reference.pthreads.worker;
+ &reference.pthreads.stackable;
&reference.pthreads.mutex;
&reference.pthreads.cond;
+
diff --git a/reference/pthreads/configure.xml b/reference/pthreads/configure.xml
index 7e0bb0858f..5e0fe35fa6 100644
--- a/reference/pthreads/configure.xml
+++ b/reference/pthreads/configure.xml
@@ -9,8 +9,10 @@
&url.pecl.package;pthreads
+
+
-
-
-
- ImportedThread::wait
- Wait for Notification from the referenced Thread.
-
-
-
- &reftitle.description;
-
- finalpublicbooleanImportedThread::wait
- longtimeout
-
-
- Causes the calling thread to block and wait for a call to Thread::notify on the referenced Thread.
- A reached timeout is regarded as failure.
- A call to Thread::wait will always result in blocking.
- The programmer should use state detection methods to avoid programming errors when using synchronization methods, Thread::wait, and Thread::notify.
-
-
-
-
- &reftitle.parameters;
-
-
- timeout
-
- An optional timeout in microseconds ( millionths of a second ).
-
-
-
-
-
-
- &reftitle.returnvalues;
- A boolean indication of success.
-
-
-
-
-
-
diff --git a/reference/pthreads/ini.xml b/reference/pthreads/ini.xml
index d4ae52f218..cdb5f3f08a 100644
--- a/reference/pthreads/ini.xml
+++ b/reference/pthreads/ini.xml
@@ -45,7 +45,7 @@
- Provides system administrators a way to limit the amount of Threads an instance of PHP can create.
+ provides system administrators a way to limit the amount of threads or workers an instance of PHP can create.
@@ -56,7 +56,7 @@
- Provides system administrators a way to disable importing threads into other context for the purposes of security.
+ provides system administrators a way to disable importing threads from other contexts for security.
diff --git a/reference/pthreads/mutex.xml b/reference/pthreads/mutex.xml
index d8b0d10afb..b7cdef2b61 100644
--- a/reference/pthreads/mutex.xml
+++ b/reference/pthreads/mutex.xml
@@ -11,15 +11,9 @@
&reftitle.intro;
- The following paragraph was taken, in part, from the Posix Threads documentation:
- Mutex is an abbreviation for "mutual exclusion". Mutex variables are one of the primary means of implementing thread synchronization and for protecting shared data when multiple writes occur.
- A mutex variable acts like a "lock" protecting access to a shared data resource. The basic concept of a mutex is that only one thread can lock (or own) a mutex variable at any given time. Thus, even if several threads try to lock a mutex only one thread will be successful. No other thread can own that mutex until the owning thread unlocks that mutex. Threads must "take turns" accessing protected data.
- Mutex can be used to prevent race conditions.
+ The static methods contained in the Mutex class provide direct access to Posix Mutex functionality.
- pthreads provides PHP with direct access to a carefully selected subset of Mutex functions.
- The Mutex created by pthreads for PHP are of an error-checking type where available (PTHREAD_MUTEX_ERRORCHECK), in the alpha stages of development this is the only type of Mutex supported by pthreads.
- Because of their nature, the programmer must take care to destroy Mutex handles they are finished with.
diff --git a/reference/pthreads/setup.xml b/reference/pthreads/setup.xml
index fb309195c0..3272c6bba6 100644
--- a/reference/pthreads/setup.xml
+++ b/reference/pthreads/setup.xml
@@ -7,28 +7,25 @@
&reftitle.required;
- pthreads requires ZTS to be enabled at build time ( --enable-maintainer-zts ).
+ pthreads requires a build of PHP with ZTS enabled ( --enable-maintainer-zts or --enable-zts on Windows )
&reftitle.install;
-
- &pecl.info;
- &url.pecl.package;pthreads.
-
-
-
- Pre-compiled Windows binaries are available on GitHub
-
-
+ &no.install;
- &reference.pthreads.ini;
+
+ &reftitle.runtime;
+ &no.config;
+
&reftitle.resources;
- &no.resource;
+
+
+
diff --git a/reference/pthreads/stackable.xml b/reference/pthreads/stackable.xml
new file mode 100644
index 0000000000..d41df970c3
--- /dev/null
+++ b/reference/pthreads/stackable.xml
@@ -0,0 +1,67 @@
+
+
+
+
+
+ The Stackable class
+ Stackable
+
+
+
+
+
+ &reftitle.intro;
+
+ Stackables are tasks that are executed by Worker threads. You can synchronize with, read, and write Stackable objects before, after and during their execution.
+
+
+
+
+
+ &reftitle.classsynopsis;
+
+
+
+ Stackable
+
+
+
+
+ Stackable
+
+
+
+
+ &Methods;
+
+
+
+
+
+
+
+
+ &reference.pthreads.entities.stackable;
+
+
+
+
diff --git a/reference/pthreads/importedthread/isrunning.xml b/reference/pthreads/stackable/getcreatorid.xml
similarity index 66%
rename from reference/pthreads/importedthread/isrunning.xml
rename to reference/pthreads/stackable/getcreatorid.xml
index 271560e4eb..20e97683f4 100644
--- a/reference/pthreads/importedthread/isrunning.xml
+++ b/reference/pthreads/stackable/getcreatorid.xml
@@ -1,19 +1,21 @@
-
+
- ImportedThread::isRunning
- Tell if the referenced Thread is running.
+ Stackable::getCreatorId
+ Identification
&reftitle.description;
- finalpublicbooleanImportedThread::isRunning
+ finalpubliclongStackable::getCreatorId
- Will return true if the referenced Thread has been started, and not yet joined by another context.
+
+ Will return the identity of the Thread that created the referenced Stackable
+
@@ -23,7 +25,9 @@
&reftitle.returnvalues;
- A boolean indication of state.
+
+ A numeric value representing the identity of the creating context
+
diff --git a/reference/pthreads/importedthread/notify.xml b/reference/pthreads/stackable/getthreadid.xml
similarity index 64%
rename from reference/pthreads/importedthread/notify.xml
rename to reference/pthreads/stackable/getthreadid.xml
index bf895e788f..6e6ec45fd7 100644
--- a/reference/pthreads/importedthread/notify.xml
+++ b/reference/pthreads/stackable/getthreadid.xml
@@ -1,21 +1,20 @@
-
+
- ImportedThread::notify
- Notify all Threads waiting for the referenced Thread.
+ Stackable::getThreadId
+ Identification
&reftitle.description;
- finalpublicbooleanImportedThread::notify
+ finalpubliclongStackable::getThreadId
- Notify all Threads waiting for the referenced Thread causing the waiting Threads to continue executing.
- A call to notify when no Threads are waiting results in blocking until another context call Thread::wait on the referenced Thread.
+ Will return the identity of the Worker Thread executing the referenced Stackable
@@ -26,10 +25,10 @@
&reftitle.returnvalues;
- A boolean indication of success.
+
+ A numeric value, which can be used within a Stackable to retrieve the Worker Thread executing the object.
+
-
-
+
-
+
- ImportedThread::join
- Join with the referenced Thread.
+ Stackable::isRunning
+ State Detection
&reftitle.description;
- finalpublicmixedImportedThread::join
+ finalpublicbooleanStackable::isRunning
- Join with the referenced Thread, and, dependant on implementation return to the caller the return value of Thread::run.
- A Thread can only be joined by one context, the programmer should use state detection to avoid programming error.
+ A Stackable is running when a Worker Thread is executing it
@@ -27,7 +26,7 @@
&reftitle.returnvalues;
-
+ A boolean indication of state
diff --git a/reference/pthreads/importedthread/iswaiting.xml b/reference/pthreads/stackable/iswaiting.xml
similarity index 66%
rename from reference/pthreads/importedthread/iswaiting.xml
rename to reference/pthreads/stackable/iswaiting.xml
index a241d71958..bb729c377f 100644
--- a/reference/pthreads/importedthread/iswaiting.xml
+++ b/reference/pthreads/stackable/iswaiting.xml
@@ -1,19 +1,21 @@
-
+
- ImportedThread::isWaiting
- Tell if the referenced Thread is waiting.
+ Stackable::isWaiting
+ State Detection
&reftitle.description;
- finalpublicbooleanImportedThread::isWaiting
+ finalpublicbooleanStackable::isWaiting
- Tell if the referenced Thread is waiting for notification from another context.
+
+ Tell if the referenced Stackable is waiting for notification
+
@@ -23,7 +25,9 @@
&reftitle.returnvalues;
- A boolean indication of state.
+
+ A boolean indication of state
+
diff --git a/reference/pthreads/importedthread/isjoined.xml b/reference/pthreads/stackable/notify.xml
similarity index 73%
rename from reference/pthreads/importedthread/isjoined.xml
rename to reference/pthreads/stackable/notify.xml
index 80d5ec86ee..e1983582ef 100644
--- a/reference/pthreads/importedthread/isjoined.xml
+++ b/reference/pthreads/stackable/notify.xml
@@ -1,24 +1,21 @@
-
+
- ImportedThread::isJoined
- Tell if the referenced Thread has been joined.
+ Stackable::notify
+ Synchronization
&reftitle.description;
- finalpublicvoidImportedThread::isJoined
+ finalpublicintStackable::notify
-
+ Sends notification to a Stackable that is waiting
-
- &warn.undocumented.func;
-
@@ -29,7 +26,7 @@
&reftitle.returnvalues;
-
+ An integral indication of success
diff --git a/reference/pthreads/stackable/run.xml b/reference/pthreads/stackable/run.xml
new file mode 100644
index 0000000000..5f3b21b60e
--- /dev/null
+++ b/reference/pthreads/stackable/run.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Stackable::run
+ Execution
+
+
+
+ &reftitle.description;
+
+ abstractpublicmixedStackable::run
+
+
+
+ The run method of a Stackable is executed by the Worker Thread
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+
+
+
+
+
+
+
+
diff --git a/reference/pthreads/importedthread/isbusy.xml b/reference/pthreads/stackable/wait.xml
similarity index 56%
rename from reference/pthreads/importedthread/isbusy.xml
rename to reference/pthreads/stackable/wait.xml
index d8459bc6ae..4dd268ec9c 100644
--- a/reference/pthreads/importedthread/isbusy.xml
+++ b/reference/pthreads/stackable/wait.xml
@@ -1,33 +1,42 @@
-
+
- ImportedThread::isBusy
- Tell if the referenced Thread is busy executing.
+ Stackable::wait
+ Synchronization
&reftitle.description;
- finalpublicbooleanImportedThread::isBusy
-
+ finalpublicintStackable::wait
+ stringtimeout
- 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.
+ Waits for notification from the Stackable
&reftitle.parameters;
- &no.function.parameters;
+
+
+ timeout
+
+
+ An optional timeout in millions of a second.
+
+
+
+
&reftitle.returnvalues;
- A boolean indication of state.
+
+ An integral indication of success
+
diff --git a/reference/pthreads/thread.xml b/reference/pthreads/thread.xml
index 5f8dde45e0..f1d02f24b6 100644
--- a/reference/pthreads/thread.xml
+++ b/reference/pthreads/thread.xml
@@ -12,7 +12,7 @@
&reftitle.intro;
- Any object that extends Thread can have the run method executed asynchronously in a Thread.
+ An implementation of a Thread should extend this declaration, implementing the run method. When the start method of that object is called, the run method code will be executed in separate Thread.
diff --git a/reference/pthreads/thread/getcount.xml b/reference/pthreads/thread/getcount.xml
index 0d9f3011b1..7b75261bf7 100644
--- a/reference/pthreads/thread/getcount.xml
+++ b/reference/pthreads/thread/getcount.xml
@@ -4,20 +4,18 @@
Thread::getCount
- Return the number of currently executing Threads.
+ Statistics
&reftitle.description;
- final
- public
- static
- int
- Thread::getCount
+ finalpublicstaticintThread::getCount
- Returns the number of currently executing Threads.
+
+ Will return the number of Threads ( including Workers ) in scope in the current instance of PHP
+
@@ -28,10 +26,11 @@
&reftitle.returnvalues;
- The number of threads that are currently running.
- This number does not include any threads that are waiting to be joined, only those that are actively executing.
+ An integral number
+
+
+
Thread::getPeak
- Return the peak number of Threads.
+ Statistics
&reftitle.description;
- finalpublicstaticintThread::getPeak
+ finalpublicstaticlongThread::getPeak
- Return the peak number of Threads executing concurrently in the current instance of PHP.
- Some system administrators choose to limit the amount of Threads an instance of PHP can create.
- If enabled the maximum number of Threads the current instance can create is returned by a call to Thread::getMax.
+ Will return the peak number of Threads the current instance has executed concurrently
- What counts as "an instance of PHP" depends on the current environment PHP and pthreads are executing in.
@@ -28,10 +25,10 @@
&reftitle.returnvalues;
- The peak number of Threads the current of PHP has executed.
+
+ An integral number
+
-
-
+
Thread::wait
- Wait for Notification from the referenced Thread.
+ Synchronization
&reftitle.description;
- finalpublicbooleanThread::wait
+ finalpublicintThread::waitlongtimeout
- Causes the calling thread to block and wait for a call to Thread::notify on the referenced Thread.
- A reached timeout is regarded as failure.
- A call to Thread::wait will always result in blocking.
- The programmer should use state detection methods to avoid programming errors when using synchronization methods, Thread::wait, and Thread::notify.
+ Will cause the calling Thread to wait for notification from the referenced Thread
@@ -27,7 +24,9 @@
timeout
- An optional timeout in microseconds ( millionths of a second ).
+
+ An optional timeout in millionths of a second
+
@@ -35,7 +34,9 @@
&reftitle.returnvalues;
- A boolean indication of success.
+
+ An integral indication of success
+
diff --git a/reference/pthreads/versions.xml b/reference/pthreads/versions.xml
index d4402d77b3..a8a6ae62fd 100644
--- a/reference/pthreads/versions.xml
+++ b/reference/pthreads/versions.xml
@@ -6,43 +6,48 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The Worker class
+ Worker
+
+
+
+
+
+ &reftitle.intro;
+
+ Worker Threads have a persistent context, as such should be used over Threads in most cases.
+
+
+
+
+
+ &reftitle.classsynopsis;
+
+
+
+ Worker
+
+
+
+
+ Worker
+
+
+
+
+ &Methods;
+
+
+
+
+
+
+
+
+ &reference.pthreads.entities.worker;
+
+
+
+
diff --git a/reference/pthreads/worker/getcreatorid.xml b/reference/pthreads/worker/getcreatorid.xml
new file mode 100644
index 0000000000..7220f20811
--- /dev/null
+++ b/reference/pthreads/worker/getcreatorid.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::getCreatorId
+ Identification
+
+
+
+ &reftitle.description;
+
+ finalpubliclongWorker::getCreatorId
+
+
+
+ Will return the identity of the Thread that created the referenced Thread
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+ A numeric value representing the identity of the creating context
+
+
+
+
+
+
+
diff --git a/reference/pthreads/importedthread/getstacked.xml b/reference/pthreads/worker/getstacked.xml
similarity index 64%
rename from reference/pthreads/importedthread/getstacked.xml
rename to reference/pthreads/worker/getstacked.xml
index 42151e9dbb..db3208fb0d 100644
--- a/reference/pthreads/importedthread/getstacked.xml
+++ b/reference/pthreads/worker/getstacked.xml
@@ -1,19 +1,21 @@
-
+
- ImportedThread::getStacked
- Return the number of items on the referenced Threads stack
+ Worker::getStacked
+ Stack Analysis
&reftitle.description;
- finalpublicintImportedThread::getStacked
+ finalpublicintWorker::getStacked
- Return the number of items waiting to be executed by the referenced Thread.
+
+ Returns the number of Stackables waiting to be executed by the referenced Worker
+
@@ -23,7 +25,9 @@
&reftitle.returnvalues;
- An intergral number representing the number of items left on the stack.
+
+ An integral value
+
diff --git a/reference/pthreads/worker/getthreadid.xml b/reference/pthreads/worker/getthreadid.xml
new file mode 100644
index 0000000000..30a021d1e4
--- /dev/null
+++ b/reference/pthreads/worker/getthreadid.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::getThreadId
+ Identification
+
+
+
+ &reftitle.description;
+
+ finalpubliclongWorker::getThreadId
+
+
+
+ Will return the identity of the referenced Worker
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+ A numeric value representing the identity of the referenced Worker
+
+
+
+
+
+
+
diff --git a/reference/pthreads/worker/isjoined.xml b/reference/pthreads/worker/isjoined.xml
new file mode 100644
index 0000000000..054d70c832
--- /dev/null
+++ b/reference/pthreads/worker/isjoined.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::isJoined
+ State Detection
+
+
+
+ &reftitle.description;
+
+ finalpublicbooleanWorker::isJoined
+
+
+
+ Tell if the referenced Worker has been joined by another context
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+ A boolean indication of state
+
+
+
+
+
+
+
diff --git a/reference/pthreads/worker/iswaiting.xml b/reference/pthreads/worker/iswaiting.xml
new file mode 100644
index 0000000000..9b02ba9f51
--- /dev/null
+++ b/reference/pthreads/worker/iswaiting.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::isWaiting
+ State Detection
+
+
+
+ &reftitle.description;
+
+ finalpublicbooleanWorker::isWaiting
+
+
+
+ Tell if the referenced Worker is waiting for notification
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+ A boolean indication of state
+
+
+
+
+
+
+
diff --git a/reference/pthreads/worker/join.xml b/reference/pthreads/worker/join.xml
new file mode 100644
index 0000000000..242fceb40a
--- /dev/null
+++ b/reference/pthreads/worker/join.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::join
+ Synchronization
+
+
+
+ &reftitle.description;
+
+ finalpublicmixedWorker::join
+
+
+
+ Causes the calling context to wait for the referenced Worker to finish executing all of the Stackables previously stacked
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+
+
+
+
+
+
+
+
diff --git a/reference/pthreads/worker/run.xml b/reference/pthreads/worker/run.xml
new file mode 100644
index 0000000000..4ba0b7dab1
--- /dev/null
+++ b/reference/pthreads/worker/run.xml
@@ -0,0 +1,55 @@
+
+
+
+
+
+ Worker::run
+ Execution
+
+
+
+ &reftitle.description;
+
+ abstractpublicmixedWorker::run
+
+
+
+ The run method of a Worker is executed before any Stackables such that the context and workers parameters may be setup in preparation for the Stackables to come
+
+
+
+
+ &reftitle.parameters;
+ &no.function.parameters;
+
+
+
+ &reftitle.returnvalues;
+
+
+
+
+
+
+
+
+
diff --git a/reference/pthreads/worker/stack.xml b/reference/pthreads/worker/stack.xml
new file mode 100644
index 0000000000..487e48dca7
--- /dev/null
+++ b/reference/pthreads/worker/stack.xml
@@ -0,0 +1,64 @@
+
+
+
+
+
+ Worker::stack
+ Stacking
+
+
+
+ &reftitle.description;
+
+ finalpublicintWorker::stack
+ Stackablework
+
+
+ Appends the referenced Stackable to the stack of the referenced Worker
+
+
+
+
+ &reftitle.parameters;
+
+
+ work
+
+
+ An object of type Stackable to be executed by the referenced Worker
+
+
+
+
+
+
+
+ &reftitle.returnvalues;
+
+ The new length of the stack
+
+
+
+
+
+
+
diff --git a/reference/pthreads/importedthread/isstarted.xml b/reference/pthreads/worker/start.xml
similarity index 52%
rename from reference/pthreads/importedthread/isstarted.xml
rename to reference/pthreads/worker/start.xml
index f5721c9640..3ed4a52bab 100644
--- a/reference/pthreads/importedthread/isstarted.xml
+++ b/reference/pthreads/worker/start.xml
@@ -1,33 +1,42 @@
-
+
- ImportedThread::isStarted
- The isStarted purpose
+ Worker::start
+ Execution
&reftitle.description;
- finalpublicbooleanImportedThread::isStarted
-
+ finalpublicbooleanWorker::start
+ booleansynchronized
- A Thread does not begin executing until a call to Thread::start.
- A Thread cannot be started twice with a call to Thread::start.
- The programmer should take care to avoid potential programming errors by calling state detection methods before attempting synchronization with another Thread.
+ Will start a new Thread, first executing Worker::run and then waiting for an executing Stackables
&reftitle.parameters;
- &no.function.parameters;
+
+
+ synchronized
+
+
+ When true will cause the calling context to wait for notification from the Worker before returning from the call to Worker::start
+
+
+
+
&reftitle.returnvalues;
- A boolean indication of state.
+
+ A boolean indication of success
+
diff --git a/reference/pthreads/worker/unstack.xml b/reference/pthreads/worker/unstack.xml
new file mode 100644
index 0000000000..ad4df2e004
--- /dev/null
+++ b/reference/pthreads/worker/unstack.xml
@@ -0,0 +1,64 @@
+
+
+
+
+
+ Worker::unstack
+ Stacking
+
+
+
+ &reftitle.description;
+
+ finalpublicintWorker::unstack
+ Stackablework
+
+
+ Removes the referenced Stackable ( or all Stackables if parameters are void ) from stack of the referenced Worker
+
+
+
+
+ &reftitle.parameters;
+
+
+ work
+
+
+ An object of type Stackable
+
+
+
+
+
+
+
+ &reftitle.returnvalues;
+
+ The new length of the stack
+
+
+
+
+
+
+