From 48096ab033a6f05eeba294cb1f4adfb0f55a8493 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Fri, 6 Oct 2017 19:42:02 +0530 Subject: [PATCH] docs: move Broker docstrings into Sphinx. --- docs/api.rst | 95 +++++++++++++++++++++++++++++++++++++--- docs/getting_started.rst | 14 ------ mitogen/core.py | 23 ---------- 3 files changed, 90 insertions(+), 42 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 673e4e65..5a7b12ed 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -355,6 +355,14 @@ Router Class masters, and child contexts who later become masters. Currently when this 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 When enabled, causes the broker thread and any subsequent broker and @@ -748,13 +756,90 @@ Broker Class ============ .. currentmodule:: mitogen.core -.. autoclass:: Broker - :members: - :inherited-members: +.. class:: Broker + + 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 ` 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 ` 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 ` on `stream` as + not ready for reading. Safe to call from any thread. + + .. method:: start_transmit (stream) + + Mark the :py:attr:`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 ` 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 -.. autoclass:: Broker - :members: +.. class:: Broker + + .. 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 ` to shutdown + gracefully before force-disconnecting them during :py:meth:`shutdown`. Utility Functions diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 7bada744..b17b2b0c 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -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 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 -------------- diff --git a/mitogen/core.py b/mitogen/core.py index 3f724f1c..ed49044d 100644 --- a/mitogen/core.py +++ b/mitogen/core.py @@ -925,15 +925,8 @@ class Router(object): class Broker(object): - """ - Responsible for tracking contexts, their associated streams and I/O - multiplexing. - """ _waker = None _thread = None - - #: Seconds grace to allow :py:class:`Streams ` to shutdown - #: gracefully before force-disconnecting them during :py:meth:`shutdown`. shutdown_timeout = 3.0 def __init__(self): @@ -958,10 +951,6 @@ class Broker(object): self._waker.wake() def start_receive(self, stream): - """Mark the :py:attr:`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) assert stream.receive_side and stream.receive_side.fd is not None self.defer(self._readers.add, stream.receive_side) @@ -1013,19 +1002,10 @@ class Broker(object): self._call(side.stream, side.stream.on_transmit) 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) + (not self._queue.empty())) 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: while self._alive: self._loop_once() @@ -1054,14 +1034,11 @@ class Broker(object): fire(self, 'exit') def shutdown(self): - """Request broker gracefully disconnect streams and stop.""" LOG.debug('%r.shutdown()', self) self._alive = False self._waker.wake() def join(self): - """Wait for the broker to stop, expected to be called after - :py:meth:`shutdown`.""" self._thread.join() def __repr__(self):