Intro

The goless library provides Go programming language semantics built on top of Stackless Python or gevent.

For an example of what goless can do, here is the Go program at https://gobyexample.com/select reimplemented with goless:

c1 = goless.chan()
c2 = goless.chan()

def func1():
    time.sleep(1)
    c1.send('one')
goless.go(func1)

def func2():
    time.sleep(2)
    c2.send('two')
goless.go(func2)

for i in range(2):
    case, val = goless.select([goless.rcase(c1), goless.rcase(c2)])
    print(val)

It is surely a testament to Go’s style that it isn’t much less Python code than Go code, but I quite like this. Don’t you?

Goroutines

The goless.go() function mimics Go’s goroutines by, unsurprisingly, running the routine in a tasklet/greenlet. If an unhandled exception occurs in a goroutine, goless.on_panic() is called.

goless.go(func, *args, **kwargs)

Run a function in a new tasklet, like a goroutine. If the goroutine raises an unhandled exception (panics), the goless.on_panic() will be called, which by default logs the error and exits the process.

Parameters:
  • args – Positional arguments to func.
  • kwargs – Keyword arguments to func.
goless.on_panic(etype, value, tb)

Called when there is an unhandled error in a goroutine. By default, logs and exits the process.

Channels

There are three types of channels available in goless. Use the goless.chan() function to create a channel. The channel implementations contain more thorough documentation about how they actually work.

goless.chan(size=0)

Returns a bidirectional channel.

A 0 or None size indicates a blocking channel (the send method will block until a receiver is available, and the recv method will block until a sender is available).

A positive integer value will return a channel with a buffer. Once the buffer is filled, the send method will block. When the buffer is empty, the recv method will block.

A negative integer will return a channel that will never block when the send method is called. The recv method will block if the buffer is empty.

Return type:goless.channels.GoChannel
class goless.channels.GoChannel

A Go-like channel that can be sent to, received from, and closed. Callers should never create this directly. Always use goless.chan() to create channels.

close()

Closes the channel, not allowing further communication. Any blocking senders or receivers will be woken up and raise goless.ChannelClosed. Receiving or sending to a closed channel will raise goless.ChannelClosed.

recv()

Receive a value from the channel. Receiving will always block if no value is available. If the channel is already closed, goless.ChannelClosed will be raised. If the channel closes during a blocking recv, goless.ChannelClosed will be raised. (#TODO)

send(value=None)

Sends the value. Blocking behavior depends on the channel type. Unbufferred channels block if no receiver is waiting. Buffered channels block if the buffer is full. Asynchronous channels never block on send.

If the channel is already closed, goless.ChannelClosed will be raised. If the channel closes during a blocking send, goless.ChannelClosed will be raised. (#TODO)

class goless.ChannelClosed

Exception raised to indicate a channel is closing or has closed.

The select function

Go’s select statement is implemented through the goless.select() function. Because Python lacks anonymous blocks (multiline lambdas), goless.select() works like Go’s reflect.Select function. Callers should create any number of goless.case classes that are passed into goless.select(). The function returns the chosen case, which the caller will usually switch off of. For example:

chan = goless.chan()
cases = [goless.rcase(chan), goless.scase(chan, 1), goless.dcase()]
chosen, value = goless.select(cases)
if chosen is cases[0]:
    print('Received %s' % value)
elif chosen is cases[1]:
    assert value is None
    print('Sent.')
else:
    assert chosen is cases[2]
    print('Default...')

Callers should never have to do anything with cases, other than create and switch off of them.

goless.select(cases)

Select the first case that becomes ready. If a default case (goless.dcase) is present, return that if no other cases are ready. If there is no default case and no case is ready, block until one becomes ready.

See Go’s reflect.Select method for an analog (http://golang.org/pkg/reflect/#Select).

Parameters:cases – List of case instances, such as goless.rcase, goless.scase, or goless.dcase.
Returns:(chosen case, received value). If the chosen case is not an goless.rcase, it will be None.
class goless.dcase

The default case.

class goless.rcase(chan)

A case that will chan.recv() when the channel is able to receive.

class goless.scase(chan, value)

A case that will chan.send(value) when the channel is able to send.

Exception Handling

Exception handling is a tricky topic and may change in the future. The default behavior right now is that an unhandled exception in a goroutine will log the exception and take down the entire process. This in theory emulates Go’s panic behavior: if a goroutine panics, the process will exit.

If you are not happy with this behavior, you should patch goless.on_panic to provide custom behavior.

If you find a better pattern, create an issue on GitHub.

Examples

The examples/ folder contains a number of examples.

In addtion, there are many examples from http://gobyexample.com implemented via goless in the tests/test_examples.py file.

If there is an example you’d like to see, or an idiomatic Go example you’d like converted, please see Contributing below.

Backends

There are two backends for concurrently available in goless.backends. These backends should only be used by goless, and not by any client code. You can choose between backends by setting the environment variable GOLESS_BACKEND to "gevent" or "stackless". Otherwise, an appropriate backend will be chosen, preferring stackless first. If neither gevent or stackless are available, a RuntimeError is raised on goless import.

goless and PyPy

goless should work under PyPy with both stackless and gevent backends.

PyPy includes a stackless.py module in its standard library, which can be used to power goless. This appears to work properly, but fails the goless test suite. We are not sure why yet, as stackless.py does not have a real maintainer and the bug is difficult to track down. However, the examples and common usages seem to all work fine.

New versions of gevent (not yet on PyPI, but in the surfly/gevent GitHub repository) work great with newer versions of PyPy.

Benchmarks

You can run benchmarks using the current Python interpreter and configured backend by running the following from the goless project directory:

$ python -m benchmark

Developers may run benchmarks locally and report them into the following table. The Go versions of the benchmarks are also run. The numbers are useful for relative comparisons only:

Current goless Benchmarks
Platform Backend Benchmark Time
go gc chan_async 0.00253
PyPy stackless chan_async 0.06400
CPython stackless chan_async 0.10000
PyPy gevent chan_async 0.35600
CPython gevent chan_async 1.09000
       
go gc chan_buff 0.00228
PyPy stackless chan_buff 0.06400
CPython stackless chan_buff 0.09000
PyPy gevent chan_buff 0.35200
CPython gevent chan_buff 1.11000
       
go gc chan_sync 0.00507
PyPy stackless chan_sync 0.06000
CPython stackless chan_sync 0.10000
PyPy gevent chan_sync 0.35200
CPython gevent chan_sync 1.09000
       
go gc select 0.03119
PyPy stackless select 0.04800
CPython stackless select 0.29000
PyPy gevent select 0.94800
CPython gevent select 1.47000
       
PyPy stackless select_default 0.00400
PyPy gevent select_default 0.00800
go gc select_default 0.02667
CPython stackless select_default 0.15000
CPython gevent select_default 0.22000

To regenerate this table, run:

$ python write_benchmarks.py

To print the table to stdout, run:

$ python write_benchresults.py -

Assuming you have Go installed, you can run the benchmarks with:

$ go run benchmark.go

goless and the GIL

goless does not address CPython’s Global Interpreter Lock (GIL) at all. goless does not magically provide any parallelization. It provides Go-like semantics, but not its performance. Perhaps this will change in the future if the GIL is removed. Another option is PyPy’s STM branch, which goless will (probably) benefit heartily.

References

Contributing

I am definitely not a Go expert, so improvements to make things more idiomatic are very welcome. Please create an issue or pull request on GitHub: https://github.com/rgalanakis/goless

goless was created by a number of people at the PyCon 2014 sprints. Even a small library like goless is the product of lots of collaboration.

Maintainers:

Special thanks:

Miscellany

Coverage is wrong. It should be higher. The coverage module does not work properly with gevent and stackless.

Indices and tables