Skip to main content

Call

Struct Call 

Source
pub struct Call { /* private fields */ }
Available on crate feature std only.
Expand description

One of our requests, awaiting its answer.

Ends in exactly one outcome: the peer’s result, or a CallError (rejected, timed out, cancelled, evicted, connection closed). Dropping a Call does not cancel the request; its answer is then discarded.

§Examples

use rpc_io::{CallError, Endpoint, Router};

let (tx, _rx) = std::sync::mpsc::channel::<String>();
let mut endpoint = Endpoint::new(tx, Router::new(), ());
let call = endpoint.peer().request("x", ())?;
// The peer answers through the endpoint:
endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"result":[42]}"#)?;
assert_eq!(call.wait().map(|raw| raw.as_str().to_owned()), Ok("[42]".to_owned()));

Implementations§

Source§

impl Call

Source

pub const fn id(&self) -> u64

The request’s id on the wire.

§Examples
let (tx, _rx) = std::sync::mpsc::channel::<String>();
let endpoint = rpc_io::Endpoint::new(tx, rpc_io::Router::new(), ()); // keep it: dropping an endpoint closes it
let peer = endpoint.peer();
assert_eq!(peer.request("a", ())?.id(), 1);
assert_eq!(peer.request("b", ())?.id(), 2);
Source

pub const fn deadline(&self) -> Option<Instant>

The deadline, if the request has one.

§Examples
let (tx, _rx) = std::sync::mpsc::channel::<String>();
let endpoint = rpc_io::Endpoint::new(tx, rpc_io::Router::new(), ()); // keep it: dropping an endpoint closes it
let peer = endpoint.peer();
assert!(peer.request("a", ())?.deadline().is_none());
Source

pub fn wait(self) -> Result<Raw<'static>, CallError>

Blocks until the answer arrives or the request ends otherwise.

§Errors

The CallError the request ended with. On the endpoint’s own thread (inside a handler) it returns CallError::WouldDeadlock at once unless the outcome is already there: that thread is the one that would read the answer.

§Examples
use rpc_io::{CallError, Endpoint, Router};

let (tx, _rx) = std::sync::mpsc::channel::<String>();
let mut endpoint = Endpoint::new(tx, Router::new(), ());
let call = endpoint.peer().request("x", ())?;
endpoint.close();
assert_eq!(call.wait(), Err(CallError::Closed));
Source

pub fn try_wait(self) -> Result<Result<Raw<'static>, CallError>, Call>

The outcome if it has arrived, or the call back to try again later. Never blocks, so a handler can poll a request it sent earlier.

§Errors

Err(self) while the request is still outstanding.

§Examples
use rpc_io::{Endpoint, Router};

let (tx, _rx) = std::sync::mpsc::channel::<String>();
let mut endpoint = Endpoint::new(tx, Router::new(), ());
let call = endpoint.peer().request("x", ())?;
let call = call.try_wait().err().unwrap(); // not answered yet
endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"result":null}"#)?;
assert!(call.try_wait().is_ok_and(|outcome| outcome.is_ok()));
Source

pub fn cancel(self) -> bool

Cancels the request: the peer is sent the cancel notification and the outcome becomes CallError::Cancelled. Returns false if the request had already ended.

§Examples
use rpc_io::{CallError, Endpoint, Router};

let (tx, rx) = std::sync::mpsc::channel::<String>();
let endpoint = Endpoint::new(tx, Router::new(), ()); // keep it: dropping an endpoint closes it
let peer = endpoint.peer();
let call = peer.request("slow", ())?;
assert!(call.cancel());
let sent: Vec<String> = rx.try_iter().collect();
assert_eq!(sent[1], r#"{"jsonrpc":"2.0","method":"$/cancelRequest","params":{"id":1}}"#);
Source

pub fn canceller(&self) -> Canceller

A handle that can cancel this request from elsewhere (another thread, a later handler) while this Call waits.

§Examples
use rpc_io::{CallError, Endpoint, Router};

let (tx, _rx) = std::sync::mpsc::channel::<String>();
let endpoint = Endpoint::new(tx, Router::new(), ()); // keep it: dropping an endpoint closes it
let peer = endpoint.peer();
let call = peer.request("slow", ())?;
let canceller = call.canceller();
std::thread::spawn(move || canceller.cancel());
assert_eq!(call.wait(), Err(CallError::Cancelled));

Trait Implementations§

Source§

impl Debug for Call

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Call

§

impl !Sync for Call

§

impl !UnwindSafe for Call

§

impl Freeze for Call

§

impl Send for Call

§

impl Unpin for Call

§

impl UnsafeUnpin for Call

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.