View Source GRPC.Stub (grpc v0.5.0)
A module acting as the interface for gRPC client.
You can do everything in the client side via GRPC.Stub, including connecting,
sending/receiving streaming or non-streaming requests, canceling calls and so on.
A service is needed to define a stub:
defmodule Greeter.Service do
use GRPC.Service, name: "ping"
rpc :SayHello, Request, Reply
rpc :SayGoodbye, stream(Request), stream(Reply)
end
defmodule Greeter.Stub do
use GRPC.Stub, service: Greeter.Service
endso that functions say_hello/2 and say_goodbye/1 will be generated for you:
# Unary call
{:ok, reply} = Greeter.Stub.say_hello(channel, request)
# Streaming call
stream = Greeter.Stub.say_goodbye(channel)
GRPC.Stub.send_request(stream, request, end_stream: true)
{:ok, reply_enum} = GRPC.Stub.recv(stream)
replies = Enum.map(reply_enum, fn({:ok, reply}) -> reply end)Note that streaming calls are very different with unary calls. If request is
streaming, the RPC function only accepts channel as argument and returns a
GRPC.Client.Stream. You can send streaming requests one by one via send_request/3,
then use recv/1 to receive the reply. And if the reply is streaming, recv/1
returns a Stream.
You can refer to call/6 for doc of your RPC functions.
Link to this section Summary
Functions
The actual function invoked when invoking a rpc function.
Cancel a stream in a streaming client.
Establish a connection with gRPC server and return GRPC.Channel needed for
sending requests.
Disconnects the adapter and frees any resources the adapter is consuming
Send END_STREAM frame to end the stream.
Receive replies when requests are streaming.
Send streaming requests.
DEPRECATED. Use send_request/3 instead
Link to this section Types
@type rpc_return() :: {:ok, struct()} | {:ok, struct(), map()} | GRPC.Client.Stream.t() | {:ok, Enumerable.t()} | {:ok, Enumerable.t(), map()} | {:error, GRPC.RPCError.t()}
Link to this section Functions
@spec call(atom(), tuple(), GRPC.Client.Stream.t(), struct() | nil, Keyword.t()) :: rpc_return()
The actual function invoked when invoking a rpc function.
returns
Returns
Unary calls.
{:ok, reply} | {:ok, headers_map} | {:error, error}- Client streaming. A
GRPC.Client.Stream Server streaming.
{:ok, Enumerable.t} | {:ok, Enumerable.t, trailers_map} | {:error, error}
options
Options
:timeout- request timeout. Default is 10s for unary calls and:infinityfor client or server streaming calls:deadline- when the request is timeout, will override timeout:metadata- a map, your custom metadata:return_headers- default is false. When it's true, a three elem tuple will be returned with the last elem being a map of headers%{headers: headers, trailers: trailers}(unary) or%{headers: headers}(server streaming)
Cancel a stream in a streaming client.
After that, callings to recv/2 will return a CANCEL error.
@spec connect(String.t(), Keyword.t()) :: {:ok, GRPC.Channel.t()} | {:error, any()}
Establish a connection with gRPC server and return GRPC.Channel needed for
sending requests.
examples
Examples
iex> GRPC.Stub.connect("localhost:50051")
{:ok, channel}
iex> GRPC.Stub.connect("localhost:50051", accepted_compressors: [GRPC.Compressor.Gzip])
{:ok, channel}
iex> GRPC.Stub.connect("/paht/to/unix.sock")
{:ok, channel}
options
Options
:cred- aGRPC.Credentialused to indicate it's a secure connection. An insecure connection will be created without this option.:adapter- custom client adapter:interceptors- client interceptors:codec- client will use this to encode and decode binary message:compressor- the client will use this to compress requests and decompress responses. If this is set, accepted_compressors will be appended also, so this can be used safely without:accepted_compressors.:accepted_compressors- tell servers accepted compressors, this can be used without:compressor:headers- headers to attach to each request
@spec connect(String.t(), binary() | non_neg_integer(), Keyword.t()) :: {:ok, GRPC.Channel.t()} | {:error, any()}
@spec disconnect(GRPC.Channel.t()) :: {:ok, GRPC.Channel.t()} | {:error, any()}
Disconnects the adapter and frees any resources the adapter is consuming
@spec end_stream(GRPC.Client.Stream.t()) :: GRPC.Client.Stream.t()
Send END_STREAM frame to end the stream.
The stream will be in half_closed state after this is called.
examples
Examples
iex> stream = GRPC.Stub.send_request(stream, request)
iex> GRPC.Stub.end_stream(stream)@spec recv(GRPC.Client.Stream.t(), Keyword.t() | map()) :: {:ok, struct()} | {:ok, struct(), map()} | {:ok, Enumerable.t()} | {:ok, Enumerable.t(), map()} | {:error, any()}
Receive replies when requests are streaming.
- If the reply is not streaming, a normal reply struct will be returned
- If the reply is streaming, a enumerable
Streamwill be returned. You can useEnumto fetch further replies orStreamto manipulate it. Each item in theEnumerableis a tuple{:ok, reply}or{:error, error}. When:return_headersis true, the last item in theEnumerablewill be{:trailers, map}
examples
Examples
# Reply is not streaming
{:ok, reply} = GRPC.Stub.recv(stream)
# Reply is streaming
{:ok, enum} = GRPC.Stub.recv(stream)
replies = Enum.map(enum, fn({:ok, reply}) -> reply end)
options
Options
:timeout- request timeout:deadline- when the request is timeout, will override timeout:return_headers- when true, headers will be returned.
@spec send_request(GRPC.Client.Stream.t(), struct(), Keyword.t()) :: GRPC.Client.Stream.t()
Send streaming requests.
The last request can be sent with :end_stream option, or you can call end_stream/1
to send a frame with END_STREAM flag to end the stream.
options
Options
:end_stream- indicates it's the last one request, then the stream will be in half_closed state. Default is false.
DEPRECATED. Use send_request/3 instead