Share Nothing, Do Everything :)
PHP has an awesome amount of extensions and features, but was conceived at a time when Web Servers were far less powerful than they are today. Almost every web server ( and mobile phone ! ) has multiple cores, if not multiple CPU's with multiple cores. PHP does not take advantage of this very well at all. While PHP is very fast to develop and express your ideas, when developing enterprising web applications we often find ourselves looking to other fully fledged languages and frameworks to write backend, or data-centric web applications because PHP isn't able to take advantage of the hardware we have at our disposal. Being able to thread in PHP makes it a real candidate for enterprising applications, and it'll make your personal home page be able to do things it simply didn't have the time to do before.
pthreads is an Object Orientated API that allows user-land multi-threading in PHP. It includes all the tools you need to create multi-threaded applications targeted at the Web or the Console. PHP applications can create, read, write and synchronize with Threads, Workers and Stackables.
A Thread Object
The user can implement a thread by extending the Thread declaration provided by pthreads. Any members can be written and read by any context with a reference to the Thread, any context can also execute any public and protected methods. The run method of the implementation is executed in a separate thread when the start method of the implementation is called from the context ( that's Thread or Process ) that created it. Only the context that creates a thread can start and join with it.
A Worker Object
A Worker Thread has a persistent state, and will be available from the call to start until the object goes out of scope, or is explicitly shutdown. Any context with a reference can pass objects of type Stackable to the Worker which will be executed by the Worker in a separate Thread. The run method of a Worker is executed before any objects on the stack, such that it can initialize resources that the Stackables to come may need.
A Stackable Object
A Stackable Object can read/write and execute the Worker Thread during the execution of it's run method, additionally, any context with a reference to the Stackable can read, write and execute it's methods before during and after execution.
All of the objects that pthreads creates have built in synchronization in the form of ::wait and ::notify. Calling ::wait on an object will cause the context to wait for another context to call ::notify on the same object. This allows for powerful synchronization between Threaded Objects in PHP.
Wait, Threaded Objects ?
A Stackable, Thread or Worker can be thought of, and should be used as a Threaded stdClass: A Thread, Worker and Stackable all behave in the same way in any context with a reference.
Any objects that are intended for use in the multi-threaded parts of your application should extend the Stackable, Thread or Worker declaration, which means they must implement run but may not ever be executed; it will often be the case that Objects being used in a multi-threaded environment are intended for execution. Doing so means any context ( that's Thread/Worker/Stackable/Process ) with a reference can read, write and execute the members of the Threaded Object before, during, and after execution.
The protected methods of Threaded Objects are protected by pthreads, such that only one context may call that method at a time. The private methods of Threaded Objects can only be called from within the Threaded Object during execution.
As a rule of thumb, any data type that can be serialized can be used as a member of a Threaded object, it can be read and written from any context with a reference to the Threaded Object. Not every type of data is stored serially, basic types are stored in their true form. Complex types, Arrays, and Objects that are not Threaded are stored serially; they can be read and written to the Threaded Object from any context with a reference.
With the exception of Threaded Objects any reference used to set a member of a Threaded Object is separated from the reference in the Threaded Object; the same data can be read directly from the Threaded Object at any time by any context with a reference to the Threaded Object.
The extensions and functionality that define resources in PHP are completely unprepared for this kind of environment; pthreads makes provisions for resources to be shared among contexts, however most types of resource WILL have problems. Most of the time, resources should NOT be shared among contexts, and when they are they should be basic types like streams and sockets.
Officially, resources remain unsupported.
A Work in Progress
pthreads was and is an experiment with pretty good results. Any of its limitations or features may change at any time; that is the nature of experimentation. It's limitations - often imposed by the implementation - exist for good reason. The aim of pthreads is to provide a useable solution to multi-tasking in PHP at any level, in the environment which pthreads executes, some restrictions and limitations are necessary in order to provide a stable environment.