Debian Codegraph @

docs/internals.rst

raw
1
2 Internal API Reference
3 **********************
4
5 .. note::
6
7 Internal APIs are subject to rapid change even across minor releases. This
8 page exists to help users modify and extend the library.
9
10
11 Constants
12 =========
13
14 .. currentmodule:: mitogen.core
15 .. autodata:: CHUNK_SIZE
16
17
18 Pollers
19 =======
20
21 .. currentmodule:: mitogen.core
22 .. autoclass:: Poller
23 :members:
24
25 .. currentmodule:: mitogen.parent
26 .. autoclass:: KqueuePoller
27
28 .. currentmodule:: mitogen.parent
29 .. autoclass:: EpollPoller
30
31 .. currentmodule:: mitogen.parent
32 .. autoclass:: PollPoller
33
34
35 Latch
36 =====
37
38 .. currentmodule:: mitogen.core
39 .. autoclass:: Latch
40 :members:
41
42
43 Logging
44 =======
45
46 See also :class:`mitogen.core.IoLoggerProtocol`.
47
48 .. currentmodule:: mitogen.core
49 .. autoclass:: LogHandler
50 :members:
51
52 .. currentmodule:: mitogen.master
53 .. autoclass:: LogForwarder
54 :members:
55
56 .. currentmodule:: mitogen.core
57 .. autoclass:: PidfulStreamHandler
58 :members:
59
60
61 Stream, Side & Protocol
62 =======================
63
64 .. currentmodule:: mitogen.core
65 .. autoclass:: Stream
66 :members:
67
68 .. currentmodule:: mitogen.core
69 .. autoclass:: BufferedWriter
70 :members:
71
72 .. currentmodule:: mitogen.core
73 .. autoclass:: Side
74 :members:
75
76 .. currentmodule:: mitogen.core
77 .. autoclass:: Protocol
78 :members:
79
80 .. currentmodule:: mitogen.parent
81 .. autoclass:: BootstrapProtocol
82 :members:
83
84 .. currentmodule:: mitogen.core
85 .. autoclass:: DelimitedProtocol
86 :members:
87
88 .. currentmodule:: mitogen.parent
89 .. autoclass:: LogProtocol
90 :members:
91
92 .. currentmodule:: mitogen.core
93 .. autoclass:: IoLoggerProtocol
94 :members:
95
96 .. currentmodule:: mitogen.core
97 .. autoclass:: MitogenProtocol
98 :members:
99
100 .. currentmodule:: mitogen.parent
101 .. autoclass:: MitogenProtocol
102 :members:
103
104 .. currentmodule:: mitogen.core
105 .. autoclass:: Waker
106 :members:
107
108
109 Connection & Options
110 ====================
111
112 .. currentmodule:: mitogen.fork
113 .. autoclass:: Options
114 :members:
115 .. autoclass:: Connection
116 :members:
117
118 .. currentmodule:: mitogen.parent
119 .. autoclass:: Options
120 :members:
121 .. autoclass:: Connection
122 :members:
123
124 .. currentmodule:: mitogen.ssh
125 .. autoclass:: Options
126 :members:
127 .. autoclass:: Connection
128 :members:
129
130 .. currentmodule:: mitogen.sudo
131 .. autoclass:: Options
132 :members:
133 .. autoclass:: Connection
134 :members:
135
136
137 Import Mechanism
138 ================
139
140 .. currentmodule:: mitogen.core
141 .. autoclass:: Importer
142 :members:
143
144 .. currentmodule:: mitogen.master
145 .. autoclass:: ModuleResponder
146 :members:
147
148 .. currentmodule:: mitogen.parent
149 .. autoclass:: ModuleForwarder
150 :members:
151
152
153 Module Finders
154 ==============
155
156 .. currentmodule:: mitogen.master
157 .. autoclass:: ModuleFinder
158 :members:
159
160 .. currentmodule:: mitogen.master
161 .. autoclass:: FinderMethod
162 :members:
163
164 .. currentmodule:: mitogen.master
165 .. autoclass:: DefectivePython3xMainMethod
166 :members:
167
168 .. currentmodule:: mitogen.master
169 .. autoclass:: PkgutilMethod
170 :members:
171
172 .. currentmodule:: mitogen.master
173 .. autoclass:: SysModulesMethod
174 :members:
175
176 .. currentmodule:: mitogen.master
177 .. autoclass:: ParentEnumerationMethod
178 :members:
179
180
181 Routing Management
182 ==================
183
184 .. currentmodule:: mitogen.parent
185 .. autoclass:: RouteMonitor
186 :members:
187
188
189 Timer Management
190 ================
191
192 .. currentmodule:: mitogen.parent
193 .. autoclass:: TimerList
194 :members:
195
196 .. currentmodule:: mitogen.parent
197 .. autoclass:: Timer
198 :members:
199
200
201 Context ID Allocation
202 =====================
203
204 .. currentmodule:: mitogen.master
205 .. autoclass:: IdAllocator
206 :members:
207
208 .. currentmodule:: mitogen.parent
209 .. autoclass:: ChildIdAllocator
210 :members:
211
212
213 Child Implementation
214 ====================
215
216 .. currentmodule:: mitogen.core
217 .. autoclass:: ExternalContext
218 :members:
219
220 .. currentmodule:: mitogen.core
221 .. autoclass:: Dispatcher
222 :members:
223
224
225 Process Management
226 ==================
227
228 .. currentmodule:: mitogen.parent
229 .. autoclass:: Reaper
230 :members:
231
232 .. currentmodule:: mitogen.parent
233 .. autoclass:: Process
234 :members:
235
236 .. currentmodule:: mitogen.parent
237 .. autoclass:: PopenProcess
238 :members:
239
240 .. currentmodule:: mitogen.fork
241 .. autoclass:: Process
242 :members:
243
244
245 Helper Functions
246 ================
247
248
249 Subprocess Functions
250 ---------------------
251
252 .. currentmodule:: mitogen.parent
253 .. autofunction:: create_child
254 .. autofunction:: hybrid_tty_create_child
255 .. autofunction:: tty_create_child
256
257
258 Helpers
259 -------
260
261 .. currentmodule:: mitogen.core
262 .. autofunction:: has_parent_authority
263 .. autofunction:: io_op
264 .. autofunction:: pipe
265 .. autofunction:: set_block
266 .. autofunction:: set_cloexec
267 .. autofunction:: set_nonblock
268 .. autofunction:: to_text
269
270 .. currentmodule:: mitogen.parent
271 .. autofunction:: create_socketpair
272
273 .. currentmodule:: mitogen.master
274 .. autofunction:: get_child_modules
275
276 .. currentmodule:: mitogen.minify
277 .. autofunction:: minimize_source
278
279
280 .. _signals:
281
282 Signals
283 =======
284
285 Mitogen contains a simplistic signal mechanism to decouple its components. When
286 a signal is fired by an instance of a class, functions registered to receive it
287 are called back.
288
289 .. warning::
290
291 As signals execute on the Broker thread, and without exception handling,
292 they are generally unsafe for consumption by user code, as any bugs could
293 trigger crashes and hangs for which the broker is unable to forward logs,
294 or ensure the buggy context always shuts down on disconnect.
295
296
297 Functions
298 ---------
299
300 .. currentmodule:: mitogen.core
301
302 .. autofunction:: listen
303 .. autofunction:: unlisten
304 .. autofunction:: fire
305
306
307 List
308 ----
309
310 These signals are used internally by Mitogen.
311
312 .. list-table::
313 :header-rows: 1
314 :widths: auto
315
316 * - Class
317 - Name
318 - Description
319
320 * - :py:class:`mitogen.core.Stream`
321 - ``disconnect``
322 - Fired on the Broker thread when disconnection is detected.
323
324 * - :py:class:`mitogen.core.Stream`
325 - ``shutdown``
326 - Fired on the Broker thread when broker shutdown begins.
327
328 * - :py:class:`mitogen.core.Context`
329 - ``disconnect``
330 - Fired on the Broker thread during shutdown (???)
331
332 * - :py:class:`mitogen.parent.Process`
333 - ``exit``
334 - Fired when :class:`mitogen.parent.Reaper` detects subprocess has fully
335 exitted.
336
337 * - :py:class:`mitogen.core.Broker`
338 - ``shutdown``
339 - Fired after Broker.shutdown() is called, but before ``shutdown`` event
340 fires. This can be used to trigger any behaviour that relies on the
341 process remaining intact, as processing of ``shutdown`` races with any
342 parent sending the child a signal because it is not shutting down in
343 reasonable time.
344
345 * - :py:class:`mitogen.core.Broker`
346 - ``shutdown``
347 - Fired after Broker.shutdown() is called.
348
349 * - :py:class:`mitogen.core.Broker`
350 - ``exit``
351 - Fired immediately prior to the broker thread exit.