Debian Codegraph @

docs/services.rst

raw
1
2 .. currentmodule:: mitogen.service
3
4 .. _service:
5
6 Service Framework
7 =================
8
9 .. warning::
10
11 This section is incomplete.
12
13 Mitogen includes a simple framework for implementing services exposed to other
14 contexts, with some built-in subclasses to capture common designs. This is a
15 work in progress, and new functionality will be added as common usage patterns
16 emerge.
17
18
19 Overview
20 --------
21
22 Service
23
24 * User-supplied class with explicitly exposed methods.
25 * May be auto-imported/constructed in a child from a parent simply by calling it
26 * Identified in calls by its canonical name (e.g. mypkg.mymod.MyClass) by
27 default, but may use any naming scheme the configured activator understands.
28 * Children receive refusals if the class is not already activated by a aprent
29 * Has an associated Select instance which may be dynamically loaded with
30 receivers over time, on_message_received() invoked if any receiver becomes
31 ready.
32
33 Invoker
34
35 * Abstracts mechanism for calling a service method and verifying permissions.
36 * Built-in 'service.Invoker': concurrent execution of all methods on the thread pool.
37 * Built-in 'service.SerializedInvoker': serialization of all calls on a single
38 thread borrowed from the pool while any request is pending.
39 * Built-in 'service.DeduplicatingInvoker': requests are aggregated by distinct
40 (method, kwargs) key, only one such method ever executes, return value is
41 cached and broadcast to all request waiters. Waiters do not block additional
42 pool threads.
43
44 Activator
45
46 * Abstracts mechanism for activating a service and verifying activation
47 permission.
48 * Built-in activator looks for service by fully.qualified.ClassName using
49 Python import mechanism, and only permits parents to trigger activation.
50
51 Pool
52
53 * Manages a fixed-size thread pool, mapping of service name to Invoker, and an
54 aggregate Select over every activate service's Selects.
55 * Constructed automatically in children in response to the first
56 CALL_SERVICE message sent to them by a parent.
57 * Must be constructed manually in parent context.
58 * Has close() and add() methods.
59
60
61 Example
62 -------
63
64 .. literalinclude:: ../examples/service/self_contained.py
65
66
67 Reference
68 ---------
69
70 .. autoclass:: mitogen.service.Policy
71 .. autoclass:: mitogen.service.AllowParents
72 .. autoclass:: mitogen.service.AllowAny
73
74 .. autofunction:: mitogen.service.arg_spec
75 .. autofunction:: mitogen.service.expose
76
77 .. autofunction:: mitogen.service.Service
78
79 .. autoclass:: mitogen.service.Invoker
80 .. autoclass:: mitogen.service.SerializedInvoker
81 .. autoclass:: mitogen.service.DeduplicatingInvoker
82
83 .. autoclass:: mitogen.service.Service
84 :members:
85
86 .. autoclass:: mitogen.service.Pool
87 :members:
88
89
90 Built-in Services
91 -----------------
92
93 .. autoclass:: mitogen.service.FileService
94 :members:
95
96 .. autoclass:: mitogen.service.PushFileService
97 :members: