xref: /aosp_15_r20/external/grpc-grpc/doc/python/sphinx/grpc_asyncio.rst (revision cc02d7e222339f7a4f6ba5f422e6413f4bd931f2)
1*cc02d7e2SAndroid Build Coastguard WorkergRPC AsyncIO API
2*cc02d7e2SAndroid Build Coastguard Worker================
3*cc02d7e2SAndroid Build Coastguard Worker
4*cc02d7e2SAndroid Build Coastguard Worker.. module:: grpc.aio
5*cc02d7e2SAndroid Build Coastguard Worker
6*cc02d7e2SAndroid Build Coastguard WorkerOverview
7*cc02d7e2SAndroid Build Coastguard Worker--------
8*cc02d7e2SAndroid Build Coastguard Worker
9*cc02d7e2SAndroid Build Coastguard WorkergRPC AsyncIO API is the **new version** of gRPC Python whose architecture is
10*cc02d7e2SAndroid Build Coastguard Workertailored to AsyncIO. Underlying, it utilizes the same C-extension, gRPC C-Core,
11*cc02d7e2SAndroid Build Coastguard Workeras existing stack, and it replaces all gRPC IO operations with methods provided
12*cc02d7e2SAndroid Build Coastguard Workerby the AsyncIO library.
13*cc02d7e2SAndroid Build Coastguard Worker
14*cc02d7e2SAndroid Build Coastguard WorkerThis API is stable. Feel free to open issues on our GitHub repo
15*cc02d7e2SAndroid Build Coastguard Worker`grpc/grpc <https://github.com/grpc/grpc>`_ for bugs or suggestions.
16*cc02d7e2SAndroid Build Coastguard Worker
17*cc02d7e2SAndroid Build Coastguard WorkerThe design doc can be found here as `gRFC <https://github.com/grpc/proposal/pull/155>`_.
18*cc02d7e2SAndroid Build Coastguard Worker
19*cc02d7e2SAndroid Build Coastguard Worker
20*cc02d7e2SAndroid Build Coastguard WorkerCaveats
21*cc02d7e2SAndroid Build Coastguard Worker-------
22*cc02d7e2SAndroid Build Coastguard Worker
23*cc02d7e2SAndroid Build Coastguard WorkergRPC Async API objects may only be used on the thread on which they were
24*cc02d7e2SAndroid Build Coastguard Workercreated. AsyncIO doesn't provide thread safety for most of its APIs.
25*cc02d7e2SAndroid Build Coastguard Worker
26*cc02d7e2SAndroid Build Coastguard Worker
27*cc02d7e2SAndroid Build Coastguard WorkerBlocking Code in AsyncIO
28*cc02d7e2SAndroid Build Coastguard Worker------------------------
29*cc02d7e2SAndroid Build Coastguard Worker
30*cc02d7e2SAndroid Build Coastguard WorkerMaking blocking function calls in coroutines or in the thread running event
31*cc02d7e2SAndroid Build Coastguard Workerloop will block the event loop, potentially starving all RPCs in the process.
32*cc02d7e2SAndroid Build Coastguard WorkerRefer to the Python language documentation on AsyncIO for more details (`running-blocking-code <https://docs.python.org/3/library/asyncio-dev.html#running-blocking-code>`_).
33*cc02d7e2SAndroid Build Coastguard Worker
34*cc02d7e2SAndroid Build Coastguard Worker
35*cc02d7e2SAndroid Build Coastguard WorkerModule Contents
36*cc02d7e2SAndroid Build Coastguard Worker---------------
37*cc02d7e2SAndroid Build Coastguard Worker
38*cc02d7e2SAndroid Build Coastguard Worker
39*cc02d7e2SAndroid Build Coastguard WorkerCreate Channel
40*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^
41*cc02d7e2SAndroid Build Coastguard Worker
42*cc02d7e2SAndroid Build Coastguard WorkerChannels are the abstraction of clients, where most of networking logic
43*cc02d7e2SAndroid Build Coastguard Workerhappens, for example, managing one or more underlying connections, name
44*cc02d7e2SAndroid Build Coastguard Workerresolution, load balancing, flow control, etc.. If you are using ProtoBuf,
45*cc02d7e2SAndroid Build Coastguard WorkerChannel objects works best when further encapsulate into stub objects, then the
46*cc02d7e2SAndroid Build Coastguard Workerapplication can invoke remote functions as if they are local functions.
47*cc02d7e2SAndroid Build Coastguard Worker
48*cc02d7e2SAndroid Build Coastguard Worker.. autofunction:: insecure_channel
49*cc02d7e2SAndroid Build Coastguard Worker.. autofunction:: secure_channel
50*cc02d7e2SAndroid Build Coastguard Worker
51*cc02d7e2SAndroid Build Coastguard Worker
52*cc02d7e2SAndroid Build Coastguard WorkerChannel Object
53*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^
54*cc02d7e2SAndroid Build Coastguard Worker
55*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: Channel
56*cc02d7e2SAndroid Build Coastguard Worker
57*cc02d7e2SAndroid Build Coastguard Worker
58*cc02d7e2SAndroid Build Coastguard WorkerCreate Server
59*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^
60*cc02d7e2SAndroid Build Coastguard Worker
61*cc02d7e2SAndroid Build Coastguard Worker.. autofunction:: server
62*cc02d7e2SAndroid Build Coastguard Worker
63*cc02d7e2SAndroid Build Coastguard Worker
64*cc02d7e2SAndroid Build Coastguard WorkerServer Object
65*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^
66*cc02d7e2SAndroid Build Coastguard Worker
67*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: Server
68*cc02d7e2SAndroid Build Coastguard Worker
69*cc02d7e2SAndroid Build Coastguard Worker
70*cc02d7e2SAndroid Build Coastguard WorkergRPC Exceptions
71*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^
72*cc02d7e2SAndroid Build Coastguard Worker
73*cc02d7e2SAndroid Build Coastguard Worker.. autoexception:: BaseError
74*cc02d7e2SAndroid Build Coastguard Worker.. autoexception:: UsageError
75*cc02d7e2SAndroid Build Coastguard Worker.. autoexception:: AbortError
76*cc02d7e2SAndroid Build Coastguard Worker.. autoexception:: InternalError
77*cc02d7e2SAndroid Build Coastguard Worker.. autoexception:: AioRpcError
78*cc02d7e2SAndroid Build Coastguard Worker
79*cc02d7e2SAndroid Build Coastguard WorkergRPC Metadata
80*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^
81*cc02d7e2SAndroid Build Coastguard Worker
82*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: Metadata
83*cc02d7e2SAndroid Build Coastguard Worker
84*cc02d7e2SAndroid Build Coastguard Worker
85*cc02d7e2SAndroid Build Coastguard WorkerRPC Context
86*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^
87*cc02d7e2SAndroid Build Coastguard Worker
88*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: RpcContext
89*cc02d7e2SAndroid Build Coastguard Worker
90*cc02d7e2SAndroid Build Coastguard Worker
91*cc02d7e2SAndroid Build Coastguard WorkerClient-Side Context
92*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^^^^
93*cc02d7e2SAndroid Build Coastguard Worker
94*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: Call
95*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryUnaryCall
96*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryStreamCall
97*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamUnaryCall
98*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamStreamCall
99*cc02d7e2SAndroid Build Coastguard Worker
100*cc02d7e2SAndroid Build Coastguard Worker
101*cc02d7e2SAndroid Build Coastguard WorkerServer-Side Context
102*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^^^^
103*cc02d7e2SAndroid Build Coastguard Worker
104*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: ServicerContext
105*cc02d7e2SAndroid Build Coastguard Worker
106*cc02d7e2SAndroid Build Coastguard Worker
107*cc02d7e2SAndroid Build Coastguard WorkerClient-Side Interceptor
108*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^^^^
109*cc02d7e2SAndroid Build Coastguard Worker
110*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: ClientCallDetails
111*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: InterceptedUnaryUnaryCall
112*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: ClientInterceptor
113*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryUnaryClientInterceptor
114*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryStreamClientInterceptor
115*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamUnaryClientInterceptor
116*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamStreamClientInterceptor
117*cc02d7e2SAndroid Build Coastguard Worker
118*cc02d7e2SAndroid Build Coastguard WorkerServer-Side Interceptor
119*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^^^^
120*cc02d7e2SAndroid Build Coastguard Worker
121*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: ServerInterceptor
122*cc02d7e2SAndroid Build Coastguard Worker
123*cc02d7e2SAndroid Build Coastguard Worker
124*cc02d7e2SAndroid Build Coastguard WorkerMulti-Callable Interfaces
125*cc02d7e2SAndroid Build Coastguard Worker^^^^^^^^^^^^^^^^^^^^^^^^^
126*cc02d7e2SAndroid Build Coastguard Worker
127*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryUnaryMultiCallable
128*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: UnaryStreamMultiCallable()
129*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamUnaryMultiCallable()
130*cc02d7e2SAndroid Build Coastguard Worker.. autoclass:: StreamStreamMultiCallable()
131