Introducing Toro, synchronization primitives for Tornado coroutines

[A. Jesse Jiryu Davis]

Hi everyone, I took a break from Motor to make "Toro": queues, semaphores, etc. for Tornado coroutines. (Tornado + Coro = "Toro".) The examples and documentation aren't quite complete, but I thought I'd share and ask for feedback:

https://github.com/ajdavis/toro

http://toro.readthedocs.org/en/latest/

The "examples" section shows use-cases for Events, Queues, and Semaphores.

If you can think of a good use-case for Lock, let me know. I'm looking for a case where a coroutine needs exclusive access to a remote resource -- that is, it needs to hold a lock while it does I/O.

Peace,
Jesse

[A. Jesse Jiryu Davis]

Also, I'd appreciate if anyone suggests language that states more clearly than I can what, exactly, Toro is for. =)

[Ben Darnell]

Looks good! I especially like that the queue implementations are
bounded; I always feel guilty when I take the easy way out and use an
unbounded queue just because I don't have a bounded async queue
available.

A quick suggestion for the docs: I'd remove JoinableQueue from the
notify/wait table, and give it and the other queues their own section,
since their interface is more complicated than a pair of methods (and
they're also less "primitive" than the others).

I assume these are not actually thread-safe; it's probably worth
calling that out explicitly so people don't think they can use these
in place of the versions from the threading module.

If you need exclusive access to an remote resource, shouldn't that
lock be maintained externally as well? I can't think of a good
example for an asynchronous local Lock (I'm not saying there aren't
any uses for it, but they're uncommon and kind of obscure).

-Ben

[A Jesse Jiryu Davis]

Thanks Ben, these are great suggestions, I'll make those changes.
You're right that these aren't thread safe and they're no help at all
in multithreaded Tornado apps.

As for Lock: Yeah, I put it in for completeness (I'm emulating Gevent
and the standard threading module) I still can't think of a use for
it. Maybe I'll wait and see if someone else comes up with one, or else
remove it from the package. Nothing depends on it, and it's just a
Semaphore(1) anyway.

[A Jesse Jiryu Davis]

I incorporated your comments:

http://toro.readthedocs.org/en/latest/index.html