Commit fb759f7c authored by David Wilson's avatar David Wilson

docs: move Broker docstrings into Sphinx.

parent 1d60c244
...@@ -355,6 +355,14 @@ Router Class ...@@ -355,6 +355,14 @@ Router Class
masters, and child contexts who later become masters. Currently when this masters, and child contexts who later become masters. Currently when this
class is required, the target context's router is upgraded at runtime. class is required, the target context's router is upgraded at runtime.
.. note::
You may construct as many routers as desired, and use the same broker
for multiple routers, however usually only one broker and router need
exist. Multiple routers may be useful when dealing with separate trust
domains, for example, manipulating infrastructure belonging to separate
customers or projects.
.. data:: profiling .. data:: profiling
When enabled, causes the broker thread and any subsequent broker and When enabled, causes the broker thread and any subsequent broker and
...@@ -748,13 +756,90 @@ Broker Class ...@@ -748,13 +756,90 @@ Broker Class
============ ============
.. currentmodule:: mitogen.core .. currentmodule:: mitogen.core
.. autoclass:: Broker .. class:: Broker
:members:
:inherited-members: Responsible for handling I/O multiplexing in a private thread.
**Note:** This is the somewhat limited core version of the Broker class
used by child contexts. The master subclass is documented below this one.
.. attribute:: shutdown_timeout = 3.0
Seconds grace to allow :py:class:`streams <Stream>` to shutdown
gracefully before force-disconnecting them during :py:meth:`shutdown`.
.. method:: defer (func, \*args, \*kwargs)
Arrange for `func(\*args, \**kwargs)` to be executed on the broker
thread, or immediately if the current thread is the broker thread. Safe
to call from any thread.
.. method:: start_receive (stream)
Mark the :py:attr:`receive_side <Stream.receive_side>` on `stream` as
ready for reading. Safe to call from any thread. When the associated
file descriptor becomes ready for reading,
:py:meth:`BasicStream.on_receive` will be called.
.. method:: stop_receive (stream)
Mark the :py:attr:`receive_side <Stream.receive_side>` on `stream` as
not ready for reading. Safe to call from any thread.
.. method:: start_transmit (stream)
Mark the :py:attr:`transmit_side <Stream.transmit_side>` on `stream` as
ready for writing. Safe to call from any thread. When the associated
file descriptor becomes ready for writing,
:py:meth:`BasicStream.on_transmit` will be called.
.. method:: stop_receive (stream)
Mark the :py:attr:`transmit_side <Stream.receive_side>` on `stream` as
not ready for writing. Safe to call from any thread.
.. method:: shutdown
Request broker gracefully disconnect streams and stop.
.. method:: join
Wait for the broker to stop, expected to be called after
:py:meth:`shutdown`.
.. method:: keep_alive
Return ``True`` if any reader's :py:attr:`Side.keep_alive` attribute is
``True``, or any :py:class:`Context` is still registered that is not
the master. Used to delay shutdown while some important work is in
progress (e.g. log draining).
**Internal Methods**
.. method:: _broker_main
Handle events until :py:meth:`shutdown`. On shutdown, invoke
:py:meth:`Stream.on_shutdown` for every active stream, then allow up to
:py:attr:`shutdown_timeout` seconds for the streams to unregister
themselves before forcefully calling
:py:meth:`Stream.on_disconnect`.
.. currentmodule:: mitogen.master .. currentmodule:: mitogen.master
.. autoclass:: Broker .. class:: Broker
:members:
.. note::
You may construct as many brokers as desired, and use the same broker
for multiple routers, however usually only one broker need exist.
Multiple brokers may be useful when dealing with sets of children with
differing lifetimes. For example, a subscription service where
non-payment results in termination for one customer.
.. attribute:: shutdown_timeout = 5.0
Seconds grace to allow :py:class:`streams <Stream>` to shutdown
gracefully before force-disconnecting them during :py:meth:`shutdown`.
Utility Functions Utility Functions
......
...@@ -83,20 +83,6 @@ If your program cannot live beneath :py:func:`mitogen.utils.run_with_router` on ...@@ -83,20 +83,6 @@ If your program cannot live beneath :py:func:`mitogen.utils.run_with_router` on
the stack, you must arrange for :py:meth:`Broker.shutdown` to be called the stack, you must arrange for :py:meth:`Broker.shutdown` to be called
anywhere the main thread may exit. anywhere the main thread may exit.
.. note::
You may construct as many routers and brokers in a process as desired, and
use the same broker for multiple routers, however in the usual case only
one broker and router need exist.
It may be useful to construct multiple routers when a service is dealing
with separate trust domains, for example, manipulating infrastructure
belonging to separate customers or separate projects.
It may be useful to construct multiple brokers when a service is dealing
with sets of children with differing lifetimes. For example, a subscription
service where non-payment results in termination for one customer.
Enable Logging Enable Logging
-------------- --------------
......
...@@ -925,15 +925,8 @@ class Router(object): ...@@ -925,15 +925,8 @@ class Router(object):
class Broker(object): class Broker(object):
"""
Responsible for tracking contexts, their associated streams and I/O
multiplexing.
"""
_waker = None _waker = None
_thread = None _thread = None
#: Seconds grace to allow :py:class:`Streams <Stream>` to shutdown
#: gracefully before force-disconnecting them during :py:meth:`shutdown`.
shutdown_timeout = 3.0 shutdown_timeout = 3.0
def __init__(self): def __init__(self):
...@@ -958,10 +951,6 @@ class Broker(object): ...@@ -958,10 +951,6 @@ class Broker(object):
self._waker.wake() self._waker.wake()
def start_receive(self, stream): def start_receive(self, stream):
"""Mark the :py:attr:`receive_side <Stream.receive_side>` on `stream` as
ready for reading. May be called from any thread. When the associated
file descriptor becomes ready for reading,
:py:meth:`BasicStream.on_transmit` will be called."""
IOLOG.debug('%r.start_receive(%r)', self, stream) IOLOG.debug('%r.start_receive(%r)', self, stream)
assert stream.receive_side and stream.receive_side.fd is not None assert stream.receive_side and stream.receive_side.fd is not None
self.defer(self._readers.add, stream.receive_side) self.defer(self._readers.add, stream.receive_side)
...@@ -1013,19 +1002,10 @@ class Broker(object): ...@@ -1013,19 +1002,10 @@ class Broker(object):
self._call(side.stream, side.stream.on_transmit) self._call(side.stream, side.stream.on_transmit)
def keep_alive(self): def keep_alive(self):
"""Return ``True`` if any reader's :py:attr:`Side.keep_alive`
attribute is ``True``, or any :py:class:`Context` is still registered
that is not the master. Used to delay shutdown while some important
work is in progress (e.g. log draining)."""
return (sum((side.keep_alive for side in self._readers), 0) + return (sum((side.keep_alive for side in self._readers), 0) +
(not self._queue.empty())) (not self._queue.empty()))
def _broker_main(self): def _broker_main(self):
"""Handle events until :py:meth:`shutdown`. On shutdown, invoke
:py:meth:`Stream.on_shutdown` for every active stream, then allow up to
:py:attr:`shutdown_timeout` seconds for the streams to unregister
themselves before forcefully calling
:py:meth:`Stream.on_disconnect`."""
try: try:
while self._alive: while self._alive:
self._loop_once() self._loop_once()
...@@ -1054,14 +1034,11 @@ class Broker(object): ...@@ -1054,14 +1034,11 @@ class Broker(object):
fire(self, 'exit') fire(self, 'exit')
def shutdown(self): def shutdown(self):
"""Request broker gracefully disconnect streams and stop."""
LOG.debug('%r.shutdown()', self) LOG.debug('%r.shutdown()', self)
self._alive = False self._alive = False
self._waker.wake() self._waker.wake()
def join(self): def join(self):
"""Wait for the broker to stop, expected to be called after
:py:meth:`shutdown`."""
self._thread.join() self._thread.join()
def __repr__(self): def __repr__(self):
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment