toro Classes

Primitives

AsyncResult

class toro.AsyncResult(io_loop=None)[source]

A one-time event that stores a value or an exception.

The only distinction between AsyncResult and a simple Future is that AsyncResult lets coroutines wait with a deadline. The deadline can be configured separately for each waiter.

An AsyncResult instance cannot be reset.

Parameters:
  • io_loop: Optional custom IOLoop.
get(deadline=None)[source]

Get a value once set() is called. Returns a Future.

The Future’s result will be the value. The Future raises toro.Timeout if no value is set before the deadline.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
get_nowait()[source]

Get the value if ready, or raise NotReady.

set(value)[source]

Set a value and wake up all the waiters.

Lock

class toro.Lock(io_loop=None)[source]

A lock for coroutines.

It is created unlocked. When unlocked, acquire() changes the state to locked. When the state is locked, yielding acquire() waits until a call to release().

The release() method should only be called in the locked state; an attempt to release an unlocked lock raises RuntimeError.

When more than one coroutine is waiting for the lock, the first one registered is awakened by release().

acquire() supports the context manager protocol:

>>> from tornado import gen
>>> import toro
>>> lock = toro.Lock()
>>>
>>> @gen.coroutine
... def f():
...    with (yield lock.acquire()):
...        assert lock.locked()
...
...    assert not lock.locked()

Note

Unlike with the standard threading.Lock, code in a single-threaded Tornado application can check if a Lock is locked(), and act on that information without fear that another thread has grabbed the lock, provided you do not yield to the IOLoop between checking locked() and using a protected resource.

Parameters:
  • io_loop: Optional custom IOLoop.
acquire(deadline=None)[source]

Attempt to lock. Returns a Future.

The Future raises toro.Timeout if the deadline passes.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
locked()[source]

True if the lock has been acquired

release()[source]

Unlock.

If any coroutines are waiting for acquire(), the first in line is awakened.

If not locked, raise a RuntimeError.

RWLock

class toro.RWLock(max_readers=1, io_loop=None)[source]

A reader-writer lock for coroutines.

It is created unlocked. When unlocked, acquire_write() always changes the state to locked. When unlocked, acquire_read() can changed the state to locked, if acquire_read() was called max_readers times. When the state is locked, yielding acquire_read()/meth:acquire_write waits until a call to release_write() in case of locking on write, or release_read() in case of locking on read.

The release_read() method should only be called in the locked-on-read state; an attempt to release an unlocked lock raises RuntimeError.

The release_write() method should only be called in the locked on write state; an attempt to release an unlocked lock raises RuntimeError.

When more than one coroutine is waiting for the lock, the first one registered is awakened by release_read()/release_write().

acquire_read()/acquire_write() support the context manager protocol:

>>> from tornado import gen
>>> import toro
>>> lock = toro.RWLock(max_readers=10)
>>>
>>> @gen.coroutine
... def f():
...    with (yield lock.acquire_read()):
...        assert not lock.locked()
...
...    with (yield lock.acquire_write()):
...        assert lock.locked()
...
...    assert not lock.locked()
Parameters:
  • max_readers: Optional max readers value, default 1.
  • io_loop: Optional custom IOLoop.
acquire_read(deadline=None)[source]

Attempt to lock for read. Returns a Future.

The Future raises toro.Timeout if the deadline passes.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
acquire_write(*args, **kwargs)[source]

Attempt to lock for write. Returns a Future.

The Future raises toro.Timeout if the deadline passes.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
locked()[source]

True if the lock has been acquired

release_read()[source]

Releases one reader.

If any coroutines are waiting for acquire_read() (in case of full readers queue), the first in line is awakened.

If not locked, raise a RuntimeError.

release_write()[source]

Releases after write.

The first in queue will be awakened after release.

If not locked, raise a RuntimeError.

Semaphore

class toro.Semaphore(value=1, io_loop=None)[source]

A lock that can be acquired a fixed number of times before blocking.

A Semaphore manages a counter representing the number of release() calls minus the number of acquire() calls, plus an initial value. The acquire() method blocks if necessary until it can return without making the counter negative.

If not given, value defaults to 1.

acquire() supports the context manager protocol:

>>> from tornado import gen
>>> import toro
>>> semaphore = toro.Semaphore()
>>>
>>> @gen.coroutine
... def f():
...    with (yield semaphore.acquire()):
...        assert semaphore.locked()
...
...    assert not semaphore.locked()

Note

Unlike the standard threading.Semaphore, a Semaphore can tell you the current value of its counter, because code in a single-threaded Tornado app can check these values and act upon them without fear of interruption from another thread.

Parameters:
  • value: An int, the initial value (default 1).
  • io_loop: Optional custom IOLoop.
acquire(deadline=None)[source]

Decrement counter. Returns a Future.

Block if the counter is zero and wait for a release(). The Future raises toro.Timeout after the deadline.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
counter

An integer, the current semaphore value

locked()[source]

True if counter is zero

release()[source]

Increment counter and wake one waiter.

wait(deadline=None)[source]

Wait for locked to be False. Returns a Future.

The Future raises toro.Timeout after the deadline.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.

BoundedSemaphore

class toro.BoundedSemaphore(value=1, io_loop=None)[source]

A semaphore that prevents release() being called too often.

A bounded semaphore checks to make sure its current value doesn’t exceed its initial value. If it does, ValueError is raised. In most situations semaphores are used to guard resources with limited capacity. If the semaphore is released too many times it’s a sign of a bug.

If not given, value defaults to 1.

Condition

class toro.Condition(io_loop=None)[source]

A condition allows one or more coroutines to wait until notified.

Like a standard Condition, but does not need an underlying lock that is acquired and released.

Parameters:
  • io_loop: Optional custom IOLoop.
notify(n=1)[source]

Wake up n waiters.

Parameters:
  • n: The number of waiters to awaken (default: 1)
notify_all()[source]

Wake up all waiters.

wait(deadline=None)[source]

Wait for notify(). Returns a Future.

Timeout is executed after a timeout.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.

Event

class toro.Event(io_loop=None)[source]

An event blocks coroutines until its internal flag is set to True.

Similar to threading.Event.

Parameters:
  • io_loop: Optional custom IOLoop.
clear()[source]

Reset the internal flag to False. Calls to wait() will block until set() is called.

is_set()[source]

Return True if and only if the internal flag is true.

set()[source]

Set the internal flag to True. All waiters are awakened. Calling wait() once the flag is true will not block.

wait(deadline=None)[source]

Block until the internal flag is true. Returns a Future.

The Future raises Timeout after a timeout.

Parameters:
  • callback: Function taking no arguments.
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.

Queues

Queue

class toro.Queue(maxsize=0, io_loop=None)[source]

Create a queue object with a given maximum size.

If maxsize is 0 (the default) the queue size is unbounded.

Unlike the standard Queue, you can reliably know this Queue’s size with qsize(), since your single-threaded Tornado application won’t be interrupted between calling qsize() and doing an operation on the Queue.

Examples:

Producer-consumer example

Queue and Semaphore example - a parallel web spider

Parameters:
  • maxsize: Optional size limit (no limit by default).
  • io_loop: Optional custom IOLoop.
empty()[source]

Return True if the queue is empty, False otherwise.

full()[source]

Return True if there are maxsize items in the queue.

Note

if the Queue was initialized with maxsize=0 (the default), then full() is never True.

get(deadline=None)[source]

Remove and return an item from the queue. Returns a Future.

The Future blocks until an item is available, or raises toro.Timeout.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
get_nowait()[source]

Remove and return an item from the queue without blocking.

Return an item if one is immediately available, else raise queue.Empty.

maxsize

Number of items allowed in the queue.

put(item, deadline=None)[source]

Put an item into the queue. Returns a Future.

The Future blocks until a free slot is available for item, or raises toro.Timeout.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
put_nowait(item)[source]

Put an item into the queue without blocking.

If no free slot is immediately available, raise queue.Full.

qsize()[source]

Number of items in the queue

PriorityQueue

class toro.PriorityQueue(maxsize=0, io_loop=None)[source]

A subclass of Queue that retrieves entries in priority order (lowest first).

Entries are typically tuples of the form: (priority number, data).

Parameters:
  • maxsize: Optional size limit (no limit by default).
  • initial: Optional sequence of initial items.
  • io_loop: Optional custom IOLoop.

LifoQueue

class toro.LifoQueue(maxsize=0, io_loop=None)[source]

A subclass of Queue that retrieves most recently added entries first.

Parameters:
  • maxsize: Optional size limit (no limit by default).
  • initial: Optional sequence of initial items.
  • io_loop: Optional custom IOLoop.

JoinableQueue

class toro.JoinableQueue(maxsize=0, io_loop=None)[source]

A subclass of Queue that additionally has task_done() and join() methods.

Parameters:
  • maxsize: Optional size limit (no limit by default).
  • initial: Optional sequence of initial items.
  • io_loop: Optional custom IOLoop.
join(deadline=None)[source]

Block until all items in the queue are processed. Returns a Future.

The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer calls task_done() to indicate that all work on the item is complete. When the count of unfinished tasks drops to zero, join() unblocks.

The Future raises toro.Timeout if the count is not zero before the deadline.

Parameters:
  • deadline: Optional timeout, either an absolute timestamp (as returned by io_loop.time()) or a datetime.timedelta for a deadline relative to the current time.
task_done()[source]

Indicate that a formerly enqueued task is complete.

Used by queue consumers. For each get used to fetch a task, a subsequent call to task_done() tells the queue that the processing on the task is complete.

If a join() is currently blocking, it will resume when all items have been processed (meaning that a task_done() call was received for every item that had been put into the queue).

Raises ValueError if called more times than there were items placed in the queue.

Exceptions

class toro.Timeout[source]

Raised when a deadline passes before a Future is ready.

class toro.NotReady[source]

Raised when accessing an AsyncResult that has no value yet.

class toro.AlreadySet[source]

Raised when setting a value on an AsyncResult that already has one.

Toro also uses exceptions Empty and Full from the standard module Queue.

Class relationships

Toro uses some of its primitives in the implementation of others. For example, JoinableQueue is a subclass of Queue, and it contains an Event. (AsyncResult stands alone.)

digraph Toro {
    graph [splines=false];
    node [shape=record];

    // First show UML-style subclass relationships.
    edge [label=subclass arrowtail=empty arrowhead=none dir=both];

    Queue -> PriorityQueue
    Queue -> LifoQueue
    Queue -> JoinableQueue
    Semaphore -> BoundedSemaphore

    // Now UML-style composition or has-a relationships.
    edge [label="has a" arrowhead=odiamond arrowtail=none];

    Event -> JoinableQueue
    Condition -> Event
    Event -> Semaphore
    Queue -> Semaphore
    Semaphore -> Lock
}