pub struct Address<A: Actor, Rc: RefCounter = Strong> { /* private fields */ }
Expand description
An Address
is a reference to an actor through which Message
s 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), Address
es are strong. Therefore, when all Address
es
are dropped, the actor will be stopped. In other words, any existing Address
es 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§
source§impl<A: Actor> Address<A, Strong>
impl<A: Actor> Address<A, Strong>
Functions which apply only to strong addresses (the default kind).
sourcepub fn downgrade(&self) -> WeakAddress<A>
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.
source§impl<A: Actor> Address<A, Either>
impl<A: Actor> Address<A, Either>
Functions which apply only to addresses which can either be strong or weak.
sourcepub fn downgrade(&self) -> WeakAddress<A>
pub fn downgrade(&self) -> WeakAddress<A>
Converts this address into a weak address.
source§impl<A: Actor, Rc: RefCounter> Address<A, Rc>
impl<A: Actor, Rc: RefCounter> Address<A, Rc>
Functions which apply to any kind of address, be they strong or weak.
sourcepub fn is_connected(&self) -> bool
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());
})
sourcepub fn as_either(&self) -> Address<A, Either>
pub fn as_either(&self) -> Address<A, Either>
Convert this address into a generic address which can be weak or strong.
sourcepub fn do_send<M>(&self, message: M) -> Result<(), Disconnected>where
M: Message,
A: Handler<M>,
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.
sourcepub fn do_send_async<M>(&self, message: M) -> DoSendFuture<A> ⓘwhere
M: Message,
A: Handler<M>,
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.
sourcepub fn send<M>(&self, message: M) -> SendFuture<A, M> ⓘwhere
M: Message,
A: Handler<M>,
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.
sourcepub 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,
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 map
ped). 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
.
sourcepub fn into_sink(self) -> AddressSink<A, Rc>
pub fn into_sink(self) -> AddressSink<A, Rc>
Converts this address into a futures Sink
.
Trait Implementations§
source§impl<A, M: Message, Rc: RefCounter> MessageChannel<M> for Address<A, Rc>where
A: Handler<M>,
impl<A, M: Message, Rc: RefCounter> MessageChannel<M> for Address<A, Rc>where
A: Handler<M>,
source§fn is_connected(&self) -> bool
fn is_connected(&self) -> bool
source§fn do_send(&self, message: M) -> Result<(), Disconnected>
fn do_send(&self, message: M) -> Result<(), Disconnected>
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.source§fn send(&self, message: M) -> SendFuture<M> ⓘ
fn send(&self, message: M) -> SendFuture<M> ⓘ
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
.source§fn attach_stream(self, stream: BoxStream<'_, M>) -> BoxFuture<'_, ()>where
M::Result: Into<KeepRunning> + Send,
fn attach_stream(self, stream: BoxStream<'_, M>) -> BoxFuture<'_, ()>where
M::Result: Into<KeepRunning> + Send,
map
ped). 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). Read moresource§fn clone_channel(&self) -> Box<dyn MessageChannel<M>>
fn clone_channel(&self) -> Box<dyn MessageChannel<M>>
source§fn sink(&self) -> Box<dyn MessageSink<M>>
fn sink(&self) -> Box<dyn MessageSink<M>>
Sink
and asynchronously send messages through it.source§impl<A, M: Message> StrongMessageChannel<M> for Address<A, Strong>where
A: Handler<M>,
impl<A, M: Message> StrongMessageChannel<M> for Address<A, Strong>where
A: Handler<M>,
source§fn upcast(self) -> Box<dyn MessageChannel<M>>
fn upcast(self) -> Box<dyn MessageChannel<M>>
Upcasts this strong message channel into a boxed generic
MessageChannel
trait object
source§fn upcast_ref(&self) -> &dyn MessageChannel<M>
fn upcast_ref(&self) -> &dyn MessageChannel<M>
Upcasts this strong message channel into a reference to the generic
MessageChannel
trait object
source§fn downgrade(&self) -> Box<dyn WeakMessageChannel<M>>
fn downgrade(&self) -> Box<dyn WeakMessageChannel<M>>
source§fn clone_channel(&self) -> Box<dyn StrongMessageChannel<M>>
fn clone_channel(&self) -> Box<dyn StrongMessageChannel<M>>
source§fn sink(&self) -> Box<dyn StrongMessageSink<M>>
fn sink(&self) -> Box<dyn StrongMessageSink<M>>
Sink
and asynchronously send messages through it.