API Reference

This document describes the functions and objects used in pyChan.

Exceptions

class chan.Error

Base exception class for chan.

Just inherits from Exception

class chan.ChanClosed(which=chan)

Since ChanClosed inherits from Error, it has the same parameters as Exception, with one addition:

Parameters:which – Keyword argument, indicating the Chan that was closed.

which

Contains the Chan object which was closed.

class chan.Timeout

Raised when an operation times out.

Chan Object

class chan.Chan(buflen=0)

Chan objects allow multiple threads to communicate.

Parameters:buflen – Defines the size of the channel’s internal buffer, or 0 if the channel should be unbuffered. An unbuffered channel blocks on all put/get’s, unless a corresponding get/put is already waiting, while a buffered channel will accept puts without blocking as long as the buffer is not full.

close()

Closes the channel, allowing no further put operations.

Once close is called, the channel allows in-progress put operations to complete and the buffer to clear, and then

closed

Returns True if the channel is closed.

It may be better to call put or get and handle the ChanClosed exception.

get(timeout=None)

Returns an item that was put onto the channel.

get returns immediately if there are items in the channel’s buffer or if another thread is blocked on put. Otherwise, it blocks until another thread puts an item onto this channel.

Parameters:timeout – An optional floating point number representing the maximum amount of time to block, in seconds. If the timeout expires, then a Timeout error is raised. Raises :ChanClosed If the channel has been closed, the buffer is empty, and no threads are waiting on put.

put(value, timeout=None)

Places an item onto the channel.

put returns immediately if the channel’s buffer has room, or if another thread is blocked on get. Otherwise, put will block until another thread calls get.

Parameters:

• value – The value to place on the channel. It is unwise to modify value afterwards, since the other thread will receive it directly, and not just a copy. It can be any type.
• timeout – An optional floating point number representing the maximum amount of time to block, in seconds. If the timeout expires, then a Timeout error is raised.

Raises :

ChanClosed If the channel has already been closed.

Multiplexing with chanselect

chan.chanselect(consumers, producers, timeout=None)

Returns when exactly one consume or produce operation succeeds.

When this function returns, either a channel is closed, or one value has been pulled from the channels in consumers, or one value has been pushed onto a channel in producers.

chanselect returns different values depending on which channel was ready first:

• (Chan, value) – If a consume channel is first.
• (Chan, None) – If a produce channel is first
• Raises ChanClosed(which=Chan) - If any channel is closed

Parameters:

• consumers – A list of Chan objects to consume from.
• producers – A list of (Chan, value), containing a channel and a value to put into the channel.
• timeout – An optional floating point number specifying the maximum amount of time to block. If no channel is ready by this time, then a Timeout error is raised.

Here’s a quick example. Let’s say we’re waiting to receive on channels chan_a and chan_b, and waiting to send on channels chan_c and chan_d. The call to chanselect looks something like this:

ch, value = chanselect([chan_a, chan_b],
                       [(chan_c, 'C'), (chan_d, 'D')])
if ch == chan_a:
    print("Got {} from A".format(value))
elif ch == chan_b:
    print("Got {} from B".format(value))
elif ch == chan_c:
    print("Sent on C")
elif ch == chan_d:
    print("Sent on D")
else:
    raise RuntimeError("Can't get here")