wiki:uGreen

uWSGI Green Threads === (available from version 0.9.5)

uGreen is an implementation of green threads ( http://en.wikipedia.org/wiki/Green_threads) on top of the uWSGI async platform.

It is very similar to python's greenlet but it is built on top of the POSIX swapcontext() function.

To take advantage of uGreen you have to set the number of async core that will be mapped to green threads.

For example if you want to spawn 30 green threads:

./uwsgi -w tests.cpubound_green -s :3031 --async 30 --ugreen

The --ugreen flag will enable uGreen on top of async mode.

Now in your app you have to simply call:

uwsgi.suspend()

to switch to another green thread.

security and performance

To ensure relative-isolation of green threads every stack area is protected by the so called "guard pages".

An attempt to write out of the stack area of a green thread will result in a segmentation fault/bus error (and the process manager, if enabled, will respawn the worker without too damages)

The context switch is very fast, we can see it as :

-> on switch

1) save the Python Frame pointer
2) save the recursion depth of the python environment (it is simply an int)
3) switch to the main stack

-> on return

1) re-set the uGreen stack
2) re-set the recursion depth
3) re-set the frame pointer

The stack/registers switch is done by POSIX' swapcontext()

I/O

For managing async I/O you can use whatever async function exported by the async mode:

uwsgi.wait_fd_read(fd, timeout)
uwsgi.wait_fd_write(fd, timeout)

Stack size

You can choose the uGreen stack size using the --ugreen-stacksize <pages>

Warning: the argument is in pages !!!

Is this better than Greenlet or Stackless python ?

It depends.

uGreen is faster (the stack is preallocated) but requires more memory (you have to allocate a stack area for every core). Stackless and Greenlet probably requires less memory and Stackless requires a heavily patched python.

Make some test to choose the best one for you (you can move from each one without changing your code)

What about python-coev ?

It gaves me a lot of idea for uGreen, and the author's way to map python threads to its implementation allows python-coev to be a little more "trustable" than stackless python. But as stackless it requires a patched version of python :(

Can i use it to write comet apps ?

In the distribution (or in the public mercurial repository) you will find the ugreenchat.py script. It is a simple/dumb multiuser comet chat:

If you want to test it (for example 30 users) run it with:

./uwsgi -s :3031 -w ugreenchat --async 30 --ugreen

The code has comments for every ugreen-related line. You need bottle (an amazing python web microframework) to use it.

Psycopg2 improvements

uGreen can benefit from the new psycopg2 async extensions and the psycogreen project.

Look at this examples:

http://projects.unbit.it/uwsgi/browser/tests/psycopg2_green.py

http://projects.unbit.it/uwsgi/browser/tests/psycogreen_green.py