toro
Classes¶
Contents
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
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, yieldingacquire()
waits until a call torelease()
.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
islocked()
, and act on that information without fear that another thread has grabbed the lock, provided you do not yield to the IOLoop between checkinglocked()
and using a protected resource.See also
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
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, ifacquire_read()
was called max_readers times. When the state is locked, yieldingacquire_read()
/meth:acquire_write waits until a call torelease_write()
in case of locking on write, orrelease_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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
-
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
-
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.
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 itscounter
, 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 raisestoro.Timeout
after the deadline.Parameters: - deadline: Optional timeout, either an absolute timestamp
(as returned by
io_loop.time()
) or adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
-
counter
¶ An integer, the current semaphore value
-
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
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¶
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 towait()
will block untilset()
is called.
-
set
()[source]¶ Set the internal flag to
True
. All waiters are awakened. Callingwait()
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 adatetime.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 callingqsize()
and doing an operation on the Queue.Examples:
Queue and Semaphore example - a parallel web spider
Parameters: - maxsize: Optional size limit (no limit by default).
- io_loop: Optional custom IOLoop.
-
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 neverTrue
.
-
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
-
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
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.
JoinableQueue¶
-
class
toro.
JoinableQueue
(maxsize=0, io_loop=None)[source]¶ A subclass of
Queue
that additionally hastask_done()
andjoin()
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 adatetime.timedelta
for a deadline relative to the current time.
- deadline: Optional timeout, either an absolute timestamp
(as returned by
-
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 totask_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 atask_done()
call was received for every item that had beenput
into the queue).Raises
ValueError
if called more times than there were items placed in the queue.
Exceptions¶
-
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.)