Struct xtra::address::Address

pub struct Address<A: Actor, Rc: RefCounter = Strong> { /* private fields */ }

An Address is a reference to an actor through which Messages can be sent. It can be cloned to create more addresses to the same actor. By default (i.e without specifying the second type parameter, Rc, to be weak), Addresses are strong. Therefore, when all Addresses are dropped, the actor will be stopped. In other words, any existing Addresses will inhibit the dropping of an actor. If this is undesirable, then a WeakAddress should be used instead. An address is created by calling the Actor::create or Context::run methods, or by cloning another Address.

Implementations

impl<A: Actor> Address<A, Strong>

Functions which apply only to strong addresses (the default kind).

pub fn downgrade(&self) -> WeakAddress<A>

Create a weak address to the actor. Unlike with the strong variety of address (this kind), an actor will not be prevented from being dropped if only weak sinks, channels, and addresses exist.

impl<A: Actor> Address<A, Either>

Functions which apply only to addresses which can either be strong or weak.

pub fn downgrade(&self) -> WeakAddress<A>

Converts this address into a weak address.

impl<A: Actor, Rc: RefCounter> Address<A, Rc>

Functions which apply to any kind of address, be they strong or weak.

pub fn is_connected(&self) -> bool

Returns whether the actor referred to by this address is running and accepting messages.

struct Shutdown;

impl Message for Shutdown {
    type Result = ();
}

#[async_trait::async_trait]
impl Handler<Shutdown> for MyActor {
    async fn handle(&mut self, _: Shutdown, ctx: &mut Context<Self>) {
        ctx.stop();
    }
}

smol::block_on(async {
    let addr = MyActor.create(None).spawn(&mut Smol::Global);
    assert!(addr.is_connected());
    addr.send(Shutdown).await;
    Timer::after(Duration::from_secs(1)).await; // Give it time to shut down
    assert!(!addr.is_connected());
})

pub fn as_either(&self) -> Address<A, Either>

Convert this address into a generic address which can be weak or strong.

pub fn do_send<M>(&self, message: M) -> Result<(), Disconnected>where
    M: Message,
    A: Handler<M>,

Send a Message to the actor without waiting for a response. If the actor’s mailbox is full, it will block. If this returns Err(Disconnected), then the actor is stopped and not accepting messages. If this returns Ok(()), the will be delivered, but may not be handled in the event that the actor stops itself (by calling Context::stop) before it was handled.

pub fn do_send_async<M>(&self, message: M) -> DoSendFuture<A> where
    M: Message,
    A: Handler<M>,

Send a Message to the actor without waiting for a response. If the actor’s mailbox is full, it will asynchronously wait. If this returns Err(Disconnected), then the actor is stopped and not accepting messages. If this returns Ok(()), the will be delivered, but may not be handled in the event that the actor stops itself (by calling Context::stop) before it was handled.

pub fn send<M>(&self, message: M) -> SendFuture<A, M> where
    M: Message,
    A: Handler<M>,

Send a Message to the actor and asynchronously wait for a response. If this returns Err(Disconnected), then the actor is stopped and not accepting messages. Like most futures, this must be polled to actually send the message.

pub async fn attach_stream<S, M, K>(self, stream: S)where
    K: Into<KeepRunning> + Send,
    M: Message<Result = K>,
    A: Handler<M>,
    S: Stream<Item = M> + Send,

Attaches a stream to this actor such that all messages produced by it are forwarded to the actor. This could, for instance, be used to forward messages from a socket to the actor (after the messages have been appropriately mapped). This is a convenience method over explicitly forwarding a stream to this address and checking when to stop forwarding.

Often, this should be spawned onto an executor to run in the background. Do not await this inside of an actor - this will cause it to await forever and never receive any messages.

Note: if this stream’s continuation should prevent the actor from being dropped, this method should be called on Address. Otherwise, it should be called on WeakAddress.

pub fn into_sink(self) -> AddressSink<A, Rc>

Converts this address into a futures Sink.

Trait Implementations

impl<A: Actor, Rc: RefCounter> Clone for Address<A, Rc>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Actor, Rc: RefCounter> Drop for Address<A, Rc>

fn drop(&mut self)

Executes the destructor for this type.

impl<A, M: Message, Rc: RefCounter> MessageChannel<M> for Address<A, Rc>where
    A: Handler<M>,

fn is_connected(&self) -> bool

Returns whether the actor referred to by this address is running and accepting messages.

fn do_send(&self, message: M) -> Result<(), Disconnected>

Send a Message to the actor without waiting for a response. If this returns Err(Disconnected), then the actor is stopped and not accepting messages. If this returns Ok(()), the will be delivered, but may not be handled in the event that the actor stops itself (by calling Context::stop) before it was handled.

fn send(&self, message: M) -> SendFuture<M>

Send a Message to the actor and asynchronously wait for a response. If this returns Err(Disconnected), then the actor is stopped and not accepting messages. This, unlike Address::send will block if the actor’s mailbox is full. If this is undesired, consider using a MessageSink.

fn attach_stream(self, stream: BoxStream<'_, M>) -> BoxFuture<'_, ()>where
    M::Result: Into<KeepRunning> + Send,

Attaches a stream to this channel such that all messages produced by it are forwarded to the actor. This could, for instance, be used to forward messages from a socket to the actor (after the messages have been appropriately mapped). This is a convenience method over explicitly forwarding a stream to this address, spawning that future onto the executor, and mapping the error away (because disconnects are expected and will simply mean that the stream is no longer being forwarded).

fn clone_channel(&self) -> Box<dyn MessageChannel<M>>

Clones this channel as a boxed trait object.

fn sink(&self) -> Box<dyn MessageSink<M>>

Use this message channel as a futures Sink and asynchronously send messages through it.

impl<A, M: Message> StrongMessageChannel<M> for Address<A, Strong>where
    A: Handler<M>,

fn upcast(self) -> Box<dyn MessageChannel<M>>

Upcasts this strong message channel into a boxed generic MessageChannel trait object

fn upcast_ref(&self) -> &dyn MessageChannel<M>

Upcasts this strong message channel into a reference to the generic MessageChannel trait object

fn downgrade(&self) -> Box<dyn WeakMessageChannel<M>>

Create a weak message channel. Unlike with the strong variety of message channel (this kind), an actor will not be prevented from being dropped if only weak sinks, channels, and addresses exist.

fn clone_channel(&self) -> Box<dyn StrongMessageChannel<M>>

Clones this channel as a boxed trait object.

fn sink(&self) -> Box<dyn StrongMessageSink<M>>

Use this message channel as a futures Sink and asynchronously send messages through it.