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; - - final public booleanImportedThread::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; - final public booleanImportedThread::isRunning + final public longStackable::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; - final public booleanImportedThread::notify + final public longStackable::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; - final public mixedImportedThread::join + final public booleanStackable::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; - final public booleanImportedThread::isWaiting + final public booleanStackable::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; - final public voidImportedThread::isJoined + final public intStackable::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; + + abstract public mixedStackable::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; - final public booleanImportedThread::isBusy - + final public intStackable::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 + final public static intThread::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; - final public static intThread::getPeak + final public static longThread::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; - final public booleanThread::wait + final public intThread::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. + 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; + + final public longWorker::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; - final public intImportedThread::getStacked + final public intWorker::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; + + final public longWorker::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; + + final public booleanWorker::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; + + final public booleanWorker::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; + + final public mixedWorker::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; + + abstract public mixedWorker::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; + + final public intWorker::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; - final public booleanImportedThread::isStarted - + final public booleanWorker::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; + + final public intWorker::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 + + + + + + +