API Reference

Protocol & Tuning

class grpclib_transports.TransportTuning(buffer_size, read_chunk_size, write_high_water, write_low_water, http2_stream_window_size, http2_connection_window_size, http2_max_frame_size, transfer_chunk_size)[source]

Buffer, window, and chunk size knobs for transport performance.

All values are in bytes. Create a tuned instance with from_env() or read the pre-computed DEFAULT_TUNING.

Fields:

buffer_size: OS pipe buffer size used when bumping subprocess pipes. read_chunk_size: Size of each read() call in the pump loop. write_high_water: High-water mark for write buffer limits. write_low_water: Low-water mark for write buffer limits. http2_stream_window_size: Per-stream HTTP/2 flow-control window. http2_connection_window_size: Connection-level HTTP/2 flow-control window. http2_max_frame_size: Maximum HTTP/2 frame size sent to the peer. transfer_chunk_size: Default chunk size for file/data chunk iterators.

Parameters:

  • buffer_size (int)

  • read_chunk_size (int)

  • write_high_water (int)

  • write_low_water (int)

  • http2_stream_window_size (int)

  • http2_connection_window_size (int)

  • http2_max_frame_size (int)

  • transfer_chunk_size (int)

grpclib_transports.DEFAULT_TUNING = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144)

Buffer, window, and chunk size knobs for transport performance.

All values are in bytes. Create a tuned instance with from_env() or read the pre-computed DEFAULT_TUNING.

Fields:

buffer_size: OS pipe buffer size used when bumping subprocess pipes. read_chunk_size: Size of each read() call in the pump loop. write_high_water: High-water mark for write buffer limits. write_low_water: Low-water mark for write buffer limits. http2_stream_window_size: Per-stream HTTP/2 flow-control window. http2_connection_window_size: Connection-level HTTP/2 flow-control window. http2_max_frame_size: Maximum HTTP/2 frame size sent to the peer. transfer_chunk_size: Default chunk size for file/data chunk iterators.

class grpclib_transports.PeerIdentity(transport, username, uid=None, gid=None, pid=None, group_ids=None, group_names=None)[source]

Identity information about the remote peer of a transport.

Fields:

transport: Transport type ("stdio", "ssh", "unix", "unknown"). username: OS username of the peer, if available. uid: Unix user ID of the peer. gid: Unix group ID of the peer. pid: Process ID of the peer. group_ids: Supplementary group IDs. group_names: Supplementary group names (resolved from group_ids).

Parameters:

  • transport (str)

  • username (str | None)

  • uid (int | None)

  • gid (int | None)

  • pid (int | None)

  • group_ids (tuple[int, ...] | None)

  • group_names (tuple[str, ...] | None)

grpclib_transports.local_process_identity(*, transport)[source]

Build a PeerIdentity for the current process.

Parameters:

transport (str)

Return type:

PeerIdentity

grpclib_transports.peer_identity_from_transport(transport)[source]

Extract PeerIdentity from an asyncio transport.

Checks for a stored peer_identity extra, an SSH username, or a Unix-domain socket with SO_PEERCRED.

Parameters:

transport (Any)

Return type:

PeerIdentity

grpclib_transports.peer_identity_from_stream(stream)[source]

Extract PeerIdentity from a gRPC stream's underlying transport.

Parameters:

stream (Any)

Return type:

PeerIdentity

grpclib_transports.make_h2_config(*, client_side)[source]

Build an h2 configuration with strict validation off.

Disables inbound/outbound header validation and normalization so protobuf-based headers pass through unchanged.

Parameters:

client_side (bool)

Return type:

H2Configuration

grpclib_transports.make_config(tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Build a grpclib Configuration with tuned window sizes.

Parameters:

tuning (TransportTuning)

Return type:

Configuration

grpclib_transports.make_server_protocol(mapping, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), status_details_codec=None)[source]

Build a server-side H2 protocol with the given handler mapping.

status_details_codec is what lets a handler's GRPCError.details reach the client: grpclib encodes it into the grpc-status-details-bin trailer only when a codec is configured, and drops it silently otherwise. The client's channel must be given the same codec to decode it.

Parameters:

  • mapping (dict[str, Handler])

  • tuning (TransportTuning)

  • status_details_codec (StatusDetailsCodecBase | None)

Return type:

H2Protocol

grpclib_transports.init_h2_transport(protocol, transport, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Wire an H2 protocol to a transport and advertise a tuned max frame size.

Parameters:
Return type:

None

grpclib_transports.build_mapping(handlers)[source]

Merge __mapping__() from a sequence of servable handlers into one dict.

Parameters:

handlers (Sequence[IServable])

Return type:

dict[str, Handler]

async grpclib_transports.pump(protocol, reader, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Read from a byte stream and feed data into an H2 protocol.

Blocks in a loop calling reader.read(). On EOF or error, calls protocol.connection_lost().

Parameters:
Return type:

None

async grpclib_transports.serve_h2(handlers, reader, transport, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency=None, status_details_codec=None)[source]

Build a server protocol, wire it to a transport, and pump frames.

Parameters:

  • handlers (Sequence[IServable])

  • reader (Any)

  • transport (Any)

  • tuning (TransportTuning)

  • max_concurrency (int | None)

  • status_details_codec (StatusDetailsCodecBase | None)

Return type:

None

grpclib_transports.pause_h2_protocol(protocol)[source]

Pause writing on an H2 protocol, if set.

Parameters:

protocol (BaseProtocol | None)

Return type:

None

grpclib_transports.resume_h2_protocol(protocol)[source]

Resume writing on an H2 protocol, if set.

Parameters:

protocol (BaseProtocol | None)

Return type:

None

grpclib_transports.signal_stop(stop)[source]

Signal a stop future, guarding against duplicate completion.

Parameters:

stop (Future[None])

Return type:

None

grpclib_transports.install_h2_fast_receive_patch()[source]

Patch h2 to skip expensive trace-logging frame reprs.

Called automatically at import time. Idempotent — subsequent calls are no-ops. Raises RuntimeError if the h2 internals have changed in a way the patch cannot handle.

Return type:

None

Transports

class grpclib_transports.BaseCustomTransport[source]

Bases: Transport

Base class for custom asyncio transports that wrap a reader/writer pair.

Concrete transports (StdioTransport, SshTransport) override: - write() — forward data to the underlying writer - get_extra_info() — delegate to the appropriate underlying object - get_write_buffer_size() — introspect the write buffer (for flow control) - abort() — hard reset (transport-specific) - can_write_eof() / write_eof() — EOF support (transport-specific)

Flow-control bridging (pause_writing/resume_writing forwarding to the H2Protocol) is handled by each concrete transport's own mechanism.

is_closing()[source]

Return True if the transport is closing or closed.

Return type:

bool

get_protocol()[source]

Return the current protocol.

Return type:

BaseProtocol

set_protocol(protocol)[source]

Set a new protocol.

Parameters:

protocol (BaseProtocol)

Return type:

None

pause_reading()[source]

Pause the receiving end.

No data will be passed to the protocol's data_received() method until resume_reading() is called.

Return type:

None

resume_reading()[source]

Resume the receiving end.

Data received will once again be passed to the protocol's data_received() method.

Return type:

None

class grpclib_transports.StdioTransport(reader, writer, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Bases: BaseCustomTransport

An asyncio transport that wraps a stdio subprocess pipe pair.

Parameters:

  • reader (asyncio.StreamReader)

  • writer (asyncio.StreamWriter)

  • tuning (TransportTuning)

write(data)[source]

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

Parameters:

data (bytes | bytearray | memoryview)

Return type:

None

get_write_buffer_size()[source]

Return the current size of the write buffer.

Return type:

int

close()[source]

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

get_extra_info(name, default=None)[source]

Get optional transport information.

Parameters:

  • name (str)

  • default (Any)

Return type:

Any

abort()[source]

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

can_write_eof()[source]

Return True if this transport supports write_eof(), False if not.

Return type:

bool

write_eof()[source]

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

Return type:

None

class grpclib_transports.SshTransport(reader, writer, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Bases: BaseCustomTransport

An asyncio transport that wraps an asyncssh channel.

Forwards asyncssh session pause_writing/resume_writing callbacks to the H2 protocol for end-to-end backpressure. Restores the original session callbacks on close or abort.

Parameters:
write(data)[source]

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

Parameters:

data (bytes | bytearray | memoryview)

Return type:

None

get_write_buffer_size()[source]

Return the current size of the write buffer.

Return type:

int

close()[source]

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

get_extra_info(name, default=None)[source]

Get optional transport information.

Parameters:

  • name (str)

  • default (Any)

Return type:

Any

abort()[source]

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

can_write_eof()[source]

Return True if this transport supports write_eof(), False if not.

Return type:

bool

write_eof()[source]

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

Return type:

None

set_write_buffer_limits(high=None, low=None)[source]

Set the high- and low-water limits for write flow control.

These two values control when to call the protocol's pause_writing() and resume_writing() methods. If specified, the low-water limit must be less than or equal to the high-water limit. Neither value can be negative.

The defaults are implementation-specific. If only the high-water limit is given, the low-water limit defaults to an implementation-specific value less than or equal to the high-water limit. Setting high to zero forces low to zero as well, and causes pause_writing() to be called whenever the buffer becomes non-empty. Setting low to zero causes resume_writing() to be called only once the buffer is empty. Use of zero for either limit is generally sub-optimal as it reduces opportunities for doing I/O and computation concurrently.

Parameters:

  • high (int | None)

  • low (int | None)

Return type:

None

class grpclib_transports.PipeTransport(reader, writer, *, transport_name='pipe', tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Bases: BaseCustomTransport

An asyncio transport that wraps a raw OS pipe pair.

Differs from StdioTransport in that it accepts arbitrary binary file objects rather than being hardwired to sys.stdin/sys.stdout.

Parameters:

  • reader (asyncio.StreamReader)

  • writer (asyncio.StreamWriter)

  • transport_name (str)

  • tuning (TransportTuning)

write(data)[source]

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

Parameters:

data (bytes | bytearray | memoryview)

Return type:

None

get_write_buffer_size()[source]

Return the current size of the write buffer.

Return type:

int

close()[source]

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

get_extra_info(name, default=None)[source]

Get optional transport information.

Parameters:

  • name (str)

  • default (Any)

Return type:

Any

abort()[source]

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

Return type:

None

can_write_eof()[source]

Return True if this transport supports write_eof(), False if not.

Return type:

bool

write_eof()[source]

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

Return type:

None

Channels

class grpclib_transports.StdioChannel(reader, writer, *, transport=None, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs)[source]

Bases: Channel

A gRPC channel that speaks H2 over a subprocess stdio pipe pair.

Parameters:
close()[source]

Closes connection to the server.

Return type:

None

class grpclib_transports.SshChannel(reader, writer, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs)[source]

Bases: Channel

A gRPC channel that speaks H2 over an asyncssh session.

Parameters:
close()[source]

Closes connection to the server.

Return type:

None

class grpclib_transports.PipeChannel(reader, writer, *, transport=None, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs)[source]

Bases: Channel

A gRPC channel that speaks H2 over a raw OS pipe pair.

Parameters:
close()[source]

Closes connection to the server.

Return type:

None

Server

class grpclib_transports.Server(*, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))[source]

Bases: object

Container for multiple service endpoints and worker managers.

Parameters:

tuning (TransportTuning)

async grpclib_transports.serve_stdio(handlers, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency=None, status_details_codec=None)[source]

Serve gRPC over the current process's stdin/stdout.

take_wire_descriptors() moves the pipe pair off descriptors 0 and 1 first, so that only H2 frames go over the wire. The redirection below adds the one case that cannot reach: a caller that replaced sys.stdout with an object of its own, which writes wherever that object writes.

Parameters:

  • handlers (list[IServable])

  • tuning (TransportTuning)

  • max_concurrency (int | None)

  • status_details_codec (StatusDetailsCodecBase | None)

Return type:

None

async grpclib_transports.serve_ssh(handlers, host='127.0.0.1', port=8022, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency=None, status_details_codec=None)[source]

Start an asyncssh server that speaks H2 on each session.

Generates an ephemeral Ed25519 key and accepts connections indefinitely. Shuts down gracefully on SIGINT or SIGTERM.

Parameters:

  • handlers (list[IServable])

  • host (str)

  • port (int)

  • tuning (TransportTuning)

  • max_concurrency (int | None)

  • status_details_codec (StatusDetailsCodecBase | None)

Return type:

None

Client

grpclib_transports.connect_ssh(host, port=22, *, username=None, password=None, known_hosts=None, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), status_details_codec=None, **kwargs)[source]

Connect to an SSH server and yield an SshChannel.

Use as an async context manager. The SSH session and channel are closed on exit.

Parameters:

  • host (str)

  • port (int)

  • username (str | None)

  • password (str | None)

  • known_hosts (Any)

  • tuning (TransportTuning)

  • status_details_codec (StatusDetailsCodecBase | None)

  • kwargs (Any)

Return type:

AsyncGenerator[SshChannel]

grpclib_transports.connect_tcp(host, port, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), ssl=None, **kwargs)[source]

Create a grpclib.client.Channel to host:port over TCP.

The channel is configured with tuned HTTP/2 window sizes from tuning. Pass ssl to enable TLS.

Parameters:

  • host (str)

  • port (int)

  • tuning (TransportTuning)

  • ssl (SSLContext | bool | None)

  • kwargs (Any)

Return type:

Channel

grpclib_transports.connect_unix(path, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs)[source]

Create a grpclib.client.Channel to a Unix-domain socket at path.

The channel is configured with tuned HTTP/2 window sizes from tuning.

Parameters:
Return type:

Channel

grpclib_transports.stdio_worker(argv, *, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), cwd=None, env=None, stderr=None, status_details_codec=None, on_process_start=None)[source]

Spawn a subprocess and yield a StdioChannel connected to its stdin/stdout.

Use as an async context manager. The subprocess is terminated on exit.

on_process_start receives the process as soon as it exists, and is the only way a caller reaches it: the channel yielded below carries the wire and nothing about the peer. multiprocessing_worker takes the same hook for the same reason. A caller needs it to read the exit status, which is what tells an abort from an ordinary exit, and to act on the pid.

Parameters:

  • argv (Sequence[str | Path])

  • tuning (TransportTuning)

  • cwd (str | Path | None)

  • env (Mapping[str, str] | None)

  • stderr (Any)

  • status_details_codec (StatusDetailsCodecBase | None)

  • on_process_start (Callable[[asyncio.subprocess.Process], None] | None)

Return type:

AsyncGenerator[StdioChannel]

Bidirectional RPC

class grpclib_transports.LogicalRpcPeer(*, send_frame, receive_frame, handler=None)[source]

Bases: object

Bidirectional RPC peer over a logical frame transport.

Supports request/response (call()), one-way events (event()), and cancellation. Spawns a background reader task via start(). Close with aclose().

Parameters:

  • send_frame (FrameSender) -- Callable that sends a LogicalFrame.

  • receive_frame (FrameReceiver) -- Callable that returns the next LogicalFrame or None.

  • handler (RequestHandler | None) -- Optional request/event handler (method, payload) -> result.

class grpclib_transports.LogicalFrame(id, kind, method=None, payload=None, error=None)[source]

A logical RPC frame exchanged between peers.

Fields:

id: Monotonic request identifier (0 for events). kind: Frame kind: "request", "response", "event", or "cancel". method: gRPC-style method name for requests/events. payload: Arbitrary data carried in the frame. error: Error message carried in a response frame.

Parameters:

  • id (int)

  • kind (Literal['request', 'response', 'event', 'cancel'])

  • method (str | None)

  • payload (Any)

  • error (str | None)

exception grpclib_transports.RemoteCallError[source]

Raised when a remote peer responds with an error.

exception grpclib_transports.PeerClosedError[source]

Raised when an operation is attempted on a closed peer.

Workers

class grpclib_transports.StdioPeerPool(argv, *, peer_factory, size=1, tuning=TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), cwd=None, env=None, stderr=None)[source]

Bases: Generic

A pool of size subprocess workers, each bridged by a LogicalRpcPeer.

Use as an async context manager. On enter, spawns size child processes via stdio_worker(), creates peers with peer_factory, and registers them in registry. On exit, closes all peers and terminates all subprocesses.

Parameters:

  • argv (Sequence[str | Path])

  • peer_factory (PeerFactory[PeerT])

  • size (int)

  • tuning (TransportTuning)

  • cwd (str | Path | None)

  • env (Mapping[str, str] | None)

  • stderr (Any)

class grpclib_transports.PeerRegistry[source]

Bases: Generic

A thread-unsafe registry of RegisteredPeer instances.

Supports len(), iteration, and snapshot via snapshot(). Broadcast calls to all registered peers with call_all().

class grpclib_transports.RegisteredPeer(id, peer, metadata=<factory>)[source]

Bases: Generic

A LogicalRpcPeer registered with an ID and optional metadata.

Delegates call() and event() to the wrapped peer.

Parameters:

  • id (str)

  • peer (PeerT)

  • metadata (Mapping[str, Any])

Transfer

grpclib_transports.iter_chunks(data, chunk_size)[source]

Yield chunk_size-byte slices of data.

Parameters:

  • data (bytes | bytearray | memoryview)

  • chunk_size (int)

Return type:

Iterator[bytes]

grpclib_transports.iter_file_chunks(path, *, chunk_size=262144)[source]

Yield chunk_size-byte chunks from the file at path.

Parameters:

  • path (str | Path)

  • chunk_size (int)

Return type:

Iterator[bytes]

Multiprocessing

class grpclib_transports.MultiprocessingPipePair(parent, child, context)[source]

Bases: object

A pair of MultiprocessingPipeEndpoint — one for parent, one for child.

Parameters:
class grpclib_transports.MultiprocessingPipeEndpoint(read_connection, write_connection, transport_name='multiprocessing')[source]

Bases: object

One end of a multiprocessing pipe pair.

Call open_channel() to create a PipeChannel backed by the pipe file descriptors.

Parameters:

  • read_connection (Any)

  • write_connection (Any)

  • transport_name (str)

grpclib_transports.multiprocessing_pipe_pair(*, context=None, preload=())[source]

Create a MultiprocessingPipePair for parent-child communication.

If context is not given, calls get_worker_context() with preload.

Parameters:

  • context (Any | None)

  • preload (Sequence[str])

Return type:

MultiprocessingPipePair

grpclib_transports.get_worker_context(method='forkserver', *, preload=())[source]

Return a multiprocessing context for method, optionally preloading modules.

preload applies to forkserver alone. It is what makes that method cheap: the forkserver imports the list once and each worker is a fork of that. No other start method has an equivalent, and asking a spawn context for one raises AttributeError.

Measured, 5 workers each, preloading one module that imports Nix:

forkserver     7.7 ms per worker
spawn         72.1 ms per worker

``spawn`` is the one that works in a forked process. multiprocessing.forkserver.ForkServer carries no pid guard, so a child that inherits a running forkserver reaches os.waitpid(self._forkserver_pid, WNOHANG) on a process that is not its own child, and ensure_running raises ChildProcessError. Measured, in a forked child:

spawn        -> start() succeeded
forkserver   -> ChildProcessError: [Errno 10] No child processes
Parameters:

  • method (str)

  • preload (Sequence[str])

Return type:

Any