Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A multithreading extension for PHP that (almost) actually works!

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 binaries
Octocat-spinner-32 deps
Octocat-spinner-32 source
Octocat-spinner-32 README.markdown
README.markdown

PHP User-land threading support

Warning

Right now this extension leaks memory like it is a feature. Each thread consumes ~1-3mb of memory that is never released. Help fixing this would be nice!

Note about Windows

Don't forget to put deps/lib/pthreadVC2.dll in the same dir as your php.exe

Contributers

Moriyoshi Koizumi: Inital code for GNU Pth and Linux

Alec Gorge: Convert code to Pthreads so it can be used with Pthreads and Pthreads-win32 plus bug fixes that may or may not have been there in Moriyoshi's release.

Summary

This adds a basic user-land threading support to the PHP scripting language. (both Windows and Linux).

A typical example (see samples directory for other ones that [should] work with the latest trunk build on both Linux and Windows)::

<?php
function print_char ($char, $times) {
    for($i = 0; $i < $times; $i++) {
        echo $char;
    }
}

echo "\nMASTER: starting threads\n";

thread_create('print_char', 'x', 2000, 50);
thread_create('print_char', 'y', 2000, 50);

echo "\nMASTER: done\n";

?>

Samples

Samples can be found at: http://github.com/alecgorge/php_threading/tree/master/source/samples/

Function list (these are your api docs presently)

PHP_FUNCTION(thread_create);
PHP_FUNCTION(thread_suspend);
PHP_FUNCTION(thread_resume);
PHP_FUNCTION(thread_join);
PHP_FUNCTION(thread_mutex_create);
PHP_FUNCTION(thread_mutex_acquire);
PHP_FUNCTION(thread_mutex_release);
PHP_FUNCTION(thread_message_queue_create);
PHP_FUNCTION(thread_message_queue_post);
PHP_FUNCTION(thread_message_queue_poll);
PHP_FUNCTION(thread_message_queue_stop);
PHP_FUNCTION(thread_message_slot_create);
PHP_FUNCTION(thread_message_slot_post);
PHP_FUNCTION(thread_message_slot_subscribe);

Why userland?

Using kernel threads in a poorly designed scripting runtime is kind of PITA because it would require a plenty of synchronization primitives (such as atomic memory operations) to be applied to the various portions of the code that prevent unserialized accesses from multiple processors. Furthermore, there are quite a few number of third-party libraries supported by PHP, most of which are unlikely designed to be reentrant in general sense.

On the other hand, user threads are much easier to handle; it guarantees every task runs in the same processor and every single operation is performed coherently, thus there would be no need to patch the PHP runtime nor add a lot of workarounds to the libraries as the behavior is much more predictable within the same process context.

Known bugs

  • Not a leak, yet the memory consumption gradually increases everytime a thread gets created and won't decrease on its termination. This is due to poor quality of the code that manages the subthreads.

Current limitations

  • This is a experimental extension (TM) and there should still be many nasty bugs.
  • A big turn-off -- threads cannot share a global context. Indeed they almost look like processes. You may call me a liar :)
  • However, classes and functions are imported to subthreads.
  • You can still pass data to a newly created thread by giving them as arguments to the entry point function.
  • Data are always duplicated when they get passed between threads.
  • Passing a container (an array or object) that contains one ore more references results in an error.
  • Only a limited kinds of resources can be passed to another thread:

    • File handles
    • Sockets
    • Thread handles
    • Mutexes
  • File handles are dup'licated on passage. Sockets aren't.

How to build PHP with thrading support (on Windows)

See included vcproj, everything is includd with a source code download. Build with VC2008. 2010 might work. Don't forget to put deps/lib/pthreadVC2.dll in the same dir as your php.exe

How to build PHP with threading support (on linux)

I have no clue, I am not a pthread gcc guru. These were the instructions for GNU Pth. If you are wise maybe you can adapt? 1 thing I do know is that you don't need to apply the patch because pthreads doesn't need it.

  1. Put the archive into ext/threading
  2. Apply function_name_redefinition_fix.diff.patch to the PHP source. (-p0)
  3. Run ./buildconf at the top of the source tree
  4. configure PHP with the following variables and flags::

    LDFLAGS="pth-config --libs --ldflags" \ CPPFLAGS="pth-config --cflags -DPTH_SYSCALL_SOFT=1" \ ./configure --with-tsrm-pth=pth-config \ --enable-maintainer-zts \ $@

  5. make && make install

  6. Enjoy!
Something went wrong with that request. Please try again.