mitogen/docs/internals.rst

352 lines
6.6 KiB
ReStructuredText
Raw Normal View History

2017-09-15 06:24:41 +00:00
Internal API Reference
**********************
2019-08-04 17:25:28 +00:00
.. note::
Internal APIs are subject to rapid change even across minor releases. This
page exists to help users modify and extend the library.
2017-09-15 06:24:41 +00:00
Constants
=========
.. currentmodule:: mitogen.core
.. autodata:: CHUNK_SIZE
Pollers
=======
.. currentmodule:: mitogen.core
.. autoclass:: Poller
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: KqueuePoller
.. currentmodule:: mitogen.parent
.. autoclass:: EpollPoller
.. currentmodule:: mitogen.parent
.. autoclass:: PollPoller
Latch
=====
2018-02-28 16:15:35 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: Latch
:members:
2018-02-28 16:15:35 +00:00
2019-08-04 17:25:28 +00:00
Logging
=======
See also :class:`mitogen.core.IoLoggerProtocol`.
.. currentmodule:: mitogen.core
.. autoclass:: LogHandler
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: LogForwarder
:members:
.. currentmodule:: mitogen.core
.. autoclass:: PidfulStreamHandler
:members:
2018-02-28 16:15:35 +00:00
2019-08-04 17:25:28 +00:00
Stream, Side & Protocol
=======================
.. currentmodule:: mitogen.core
.. autoclass:: Stream
:members:
2017-09-15 06:24:41 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: BufferedWriter
:members:
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: Side
:members:
2017-09-15 06:24:41 +00:00
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: Protocol
:members:
2017-09-15 06:24:41 +00:00
.. currentmodule:: mitogen.parent
.. autoclass:: BootstrapProtocol
:members:
.. currentmodule:: mitogen.core
.. autoclass:: DelimitedProtocol
2017-09-15 06:24:41 +00:00
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: LogProtocol
:members:
.. currentmodule:: mitogen.core
.. autoclass:: IoLoggerProtocol
2017-09-15 06:24:41 +00:00
:members:
.. currentmodule:: mitogen.core
.. autoclass:: MitogenProtocol
2017-09-29 14:52:43 +00:00
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: MitogenProtocol
2017-09-15 06:24:41 +00:00
:members:
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: Waker
2017-09-15 06:24:41 +00:00
:members:
Connection & Options
====================
.. currentmodule:: mitogen.fork
.. autoclass:: Options
:members:
.. autoclass:: Connection
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: Options
:members:
.. autoclass:: Connection
:members:
.. currentmodule:: mitogen.ssh
.. autoclass:: Options
:members:
.. autoclass:: Connection
:members:
.. currentmodule:: mitogen.sudo
.. autoclass:: Options
:members:
.. autoclass:: Connection
2017-09-15 06:24:41 +00:00
:members:
2019-08-04 17:25:28 +00:00
Import Mechanism
================
.. currentmodule:: mitogen.core
.. autoclass:: Importer
:members:
.. currentmodule:: mitogen.master
.. autoclass:: ModuleResponder
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.parent
.. autoclass:: ModuleForwarder
:members:
2019-08-04 17:25:28 +00:00
Module Finders
==============
2018-10-31 15:06:28 +00:00
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: ModuleFinder
2018-10-31 15:06:28 +00:00
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: FinderMethod
:members:
2018-10-31 15:06:28 +00:00
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: DefectivePython3xMainMethod
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: PkgutilMethod
:members:
.. currentmodule:: mitogen.master
.. autoclass:: SysModulesMethod
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.master
.. autoclass:: ParentEnumerationMethod
:members:
2019-08-04 17:25:28 +00:00
Routing Management
==================
.. currentmodule:: mitogen.parent
2019-08-04 17:25:28 +00:00
.. autoclass:: RouteMonitor
:members:
2019-08-04 17:25:28 +00:00
Timer Management
================
.. currentmodule:: mitogen.parent
2019-08-04 17:25:28 +00:00
.. autoclass:: TimerList
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: Timer
:members:
Context ID Allocation
=====================
.. currentmodule:: mitogen.master
.. autoclass:: IdAllocator
:members:
.. currentmodule:: mitogen.parent
.. autoclass:: ChildIdAllocator
:members:
2019-08-04 17:25:28 +00:00
Child Implementation
====================
2017-09-15 06:24:41 +00:00
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: ExternalContext
:members:
2017-09-29 14:52:43 +00:00
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.core
.. autoclass:: Dispatcher
:members:
2017-09-15 06:24:41 +00:00
2019-08-04 17:25:28 +00:00
Process Management
==================
.. currentmodule:: mitogen.parent
.. autoclass:: Reaper
:members:
2019-08-04 17:25:28 +00:00
.. currentmodule:: mitogen.parent
.. autoclass:: Process
:members:
2017-09-15 06:24:41 +00:00
.. currentmodule:: mitogen.parent
2019-08-04 17:25:28 +00:00
.. autoclass:: PopenProcess
:members:
.. currentmodule:: mitogen.fork
.. autoclass:: Process
:members:
2019-08-04 17:25:28 +00:00
Helper Functions
================
Subprocess Functions
---------------------
2018-08-18 13:33:55 +00:00
.. currentmodule:: mitogen.parent
.. autofunction:: create_child
.. autofunction:: hybrid_tty_create_child
.. autofunction:: tty_create_child
2017-09-15 06:24:41 +00:00
Helpers
-------
2017-09-15 06:24:41 +00:00
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.core
.. autofunction:: has_parent_authority
.. autofunction:: io_op
.. autofunction:: pipe
.. autofunction:: set_block
.. autofunction:: set_cloexec
.. autofunction:: set_nonblock
.. autofunction:: to_text
2017-09-29 14:52:43 +00:00
2018-08-18 14:16:12 +00:00
.. currentmodule:: mitogen.parent
.. autofunction:: create_socketpair
2017-09-18 09:20:41 +00:00
2017-09-29 14:52:43 +00:00
.. currentmodule:: mitogen.master
2018-08-18 13:33:55 +00:00
.. autofunction:: get_child_modules
2018-07-08 21:00:00 +00:00
.. currentmodule:: mitogen.minify
2018-08-18 13:33:55 +00:00
.. autofunction:: minimize_source
2018-05-04 02:47:29 +00:00
.. _signals:
2018-05-04 02:47:29 +00:00
Signals
=======
Mitogen contains a simplistic signal mechanism to decouple its components. When
a signal is fired by an instance of a class, functions registered to receive it
are called back.
.. warning::
As signals execute on the Broker thread, and without exception handling,
they are generally unsafe for consumption by user code, as any bugs could
trigger crashes and hangs for which the broker is unable to forward logs,
or ensure the buggy context always shuts down on disconnect.
Functions
---------
.. currentmodule:: mitogen.core
.. autofunction:: listen
.. autofunction:: unlisten
.. autofunction:: fire
List
----
These signals are used internally by Mitogen.
.. list-table::
:header-rows: 1
:widths: auto
* - Class
- Name
- Description
* - :py:class:`mitogen.core.Stream`
- ``disconnect``
- Fired on the Broker thread when disconnection is detected.
* - :py:class:`mitogen.core.Stream`
- ``shutdown``
- Fired on the Broker thread when broker shutdown begins.
* - :py:class:`mitogen.core.Context`
- ``disconnect``
- Fired on the Broker thread during shutdown (???)
* - :py:class:`mitogen.parent.Process`
- ``exit``
- Fired when :class:`mitogen.parent.Reaper` detects subprocess has fully
exitted.
* - :py:class:`mitogen.core.Broker`
- ``shutdown``
- Fired after Broker.shutdown() is called, but before ``shutdown`` event
fires. This can be used to trigger any behaviour that relies on the
process remaining intact, as processing of ``shutdown`` races with any
parent sending the child a signal because it is not shutting down in
reasonable time.
* - :py:class:`mitogen.core.Broker`
- ``shutdown``
- Fired after Broker.shutdown() is called.
* - :py:class:`mitogen.core.Broker`
- ``exit``
- Fired immediately prior to the broker thread exit.