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, execute and synchronize with Threads, Workers and Threaded objects.
A Threaded Object: A Threaded Object forms the basis of the functionality that allows pthreads to operate. It exposes synchronization methods and some useful interfaces for the programmer.
A Thread: The user can implement a Thread by extending the Thread declaration provided by pthreads implementing the run method. 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 stack objects onto 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 objects to come may need.
A Pool: A Pool of Worker threads can be used to distribute Threaded objects among Workers. The Pool class included implements this functionality and takes care of referencing in a sane manner. Introduced in v1.0.0, the Pool implementation is the easiest and most efficient way of using multiple threads.
Pool is a normal PHP object, and so instances should not be shared among contexts.
Synchronization: All of the objects that pthreads creates have built in synchronization in the ( familiar to java programmers ) 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.
Any objects that are intended for use in the multi-threaded parts of your application should extend Threaded.
Method Modifiers: 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.
Data Storage: 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.
Static Members: When a new context is created ( Thread or Worker ), only the simple members of static classes are copied, no resources, objects or arrays are copied into the threading context from static class members. This allows them to function as a kind of thread local storage. For example, upon starting the context, a class whose static members include connection information for a database server, and the connection itself, will only have the simple connection information copied, not the connection. Allowing the new context to initiate a connection in the same way as the context that created it, storing the connection in the same place without affecting the original context.
When print_r, var_dump and other object debug functions are executed, they do not include recursion protection.
Note:
Resources: 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, for most types of resource it should be considered unsafe. Extreme caution and care should be used when sharing resources among contexts.
In the environment which pthreads executes, some restrictions and limitations are necessary in order to provide a stable environment.