Added trampoline docs, made a note about internal APIs (and learned a bit about sphinx at the same time).
This commit is contained in:
parent
2574c30f9d
commit
d89b4bfc5a
|
@ -0,0 +1,4 @@
|
||||||
|
.. |internal| replace::
|
||||||
|
|
||||||
|
This is considered an internal API, and it might change
|
||||||
|
unexpectedly without being deprecated first.
|
14
doc/hubs.rst
14
doc/hubs.rst
|
@ -35,14 +35,18 @@ If the selected hub is not idea for the application, another can be selected.
|
||||||
Supplying None as the argument to :func:`eventlet.hubs.use_hub` causes it to select the default hub.
|
Supplying None as the argument to :func:`eventlet.hubs.use_hub` causes it to select the default hub.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. autofunction:: eventlet.hubs.get_hub
|
|
||||||
.. autofunction:: eventlet.hubs.get_default_hub
|
|
||||||
|
|
||||||
How the Hubs Work
|
How the Hubs Work
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
The hub has a main greenlet, MAINLOOP. When one of the running coroutines needs
|
The hub has a main greenlet, MAINLOOP. When one of the running coroutines needs
|
||||||
to do some I/O, it registers a listener with the hub (so that the hub knows when to wake it up again), and then switches to MAINLOOP (via ``get_hub().switch()``). If there are other coroutines that are ready to run, MAINLOOP switches to them, and when they complete or need to do more I/O, they switch back to the MAINLOOP. In this manner, MAINLOOP ensures that every coroutine gets scheduled when it has some work to do.
|
to do some I/O, it registers a listener with the hub (so that the hub knows when to wake it up again), and then switches to MAINLOOP (via ``get_hub().switch()``). If there are other coroutines that are ready to run, MAINLOOP switches to them, and when they complete or need to do more I/O, they switch back to the MAINLOOP. In this manner, MAINLOOP ensures that every coroutine gets scheduled when it has some work to do.
|
||||||
|
|
||||||
MAINLOOP is launched only when the first I/O operation happens, and it is not the same greenlet that __main__ is running in. This lazy launching is why it's not necessary to explicitly call a dispatch() method like other frameworks, which in turn means that code can start using Eventlet without needing to be substantially restructured.
|
MAINLOOP is launched only when the first I/O operation happens, and it is not the same greenlet that __main__ is running in. This lazy launching is why it's not necessary to explicitly call a dispatch() method like other frameworks, which in turn means that code can start using Eventlet without needing to be substantially restructured.
|
||||||
|
|
||||||
|
More Hub-Related Functions
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. autofunction:: eventlet.hubs.get_hub
|
||||||
|
.. autofunction:: eventlet.hubs.get_default_hub
|
||||||
|
.. autofunction:: eventlet.hubs.trampoline
|
||||||
|
|
||||||
|
|
|
@ -15,8 +15,11 @@ def get_default_hub():
|
||||||
* poll
|
* poll
|
||||||
* select
|
* select
|
||||||
|
|
||||||
It won't ever automatically select the pyevent hub, because it's not
|
It won't automatically select the pyevent hub, because it's not
|
||||||
python-thread-safe.
|
python-thread-safe.
|
||||||
|
|
||||||
|
.. include:: ../../doc/common.txt
|
||||||
|
.. note :: |internal|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
# pyevent hub disabled for now because it is not thread-safe
|
# pyevent hub disabled for now because it is not thread-safe
|
||||||
|
@ -67,6 +70,8 @@ def use_hub(mod=None):
|
||||||
|
|
||||||
def get_hub():
|
def get_hub():
|
||||||
"""Get the current event hub singleton object.
|
"""Get the current event hub singleton object.
|
||||||
|
|
||||||
|
.. note :: |internal|
|
||||||
"""
|
"""
|
||||||
try:
|
try:
|
||||||
hub = _threadlocal.hub
|
hub = _threadlocal.hub
|
||||||
|
@ -95,6 +100,8 @@ def trampoline(fd, read=None, write=None, timeout=None,
|
||||||
If the specified *timeout* elapses before the socket is ready to read or
|
If the specified *timeout* elapses before the socket is ready to read or
|
||||||
write, *timeout_exc* will be raised instead of ``trampoline()``
|
write, *timeout_exc* will be raised instead of ``trampoline()``
|
||||||
returning normally.
|
returning normally.
|
||||||
|
|
||||||
|
.. note :: |internal|
|
||||||
"""
|
"""
|
||||||
t = None
|
t = None
|
||||||
hub = get_hub()
|
hub = get_hub()
|
||||||
|
|
Loading…
Reference in New Issue