Struct heph::actor_ref::ActorRef

pub struct ActorRef<M> { /* private fields */ }

Actor reference.

An actor reference reference can be used to send messages to an actor, for more details see the module documentation.

Implementations

impl<M> ActorRef<M>

pub fn send<'r, Msg>(&'r self, msg: Msg) -> SendValue<'r, M> where
    Msg: Into<M>, 

Send a message to the actor.

See Sending messages and ActorRef::try_send for more details.

Notes

Mapped actor references, see ActorRef::map and ActorRef::try_map, require an allocation and might be expensive. If possible try ActorRef::try_send first, which does not require an allocation. Regular (i.e. non-mapped) actor references do not require an allocation.

pub fn try_send<Msg>(&self, msg: Msg) -> Result<(), SendError> where
    Msg: Into<M>, 

Attempt to send a message to the actor.

Some types of actor references can detect errors in sending a message, however not all actor references can. This means that even if this methods returns Ok it does not mean that the message is guaranteed to be delivered to or handled by the actor.

See Sending messages for more details.

pub fn rpc<'r, Req, Res>(&'r self, request: Req) -> Rpc<'r, M, Res> where
    M: From<RpcMessage<Req, Res>>, 

Make a Remote Procedure Call (RPC).

This will send the request to the actor and returns a Rpc Future that will return a response (of type Res), or an error if the receiving actor didn’t respond.

See the rpc module for more details.

pub fn map<Msg>(self) -> ActorRef<Msg> where
    M: From<Msg> + 'static,
    Msg: 'static, 

Change the message type of the actor reference.

Before sending the message this will first change the message into a different type. This is useful when you need to send to different types of actors (using different message types) from a central location.

Notes

This conversion is not cheap, it requires an allocation so use with caution when it comes to performance sensitive code.

Prefer to clone an existing mapped ActorRef over creating a new one as that can reuse the allocation mentioned above.

pub fn try_map<Msg>(self) -> ActorRef<Msg> where
    M: TryFrom<Msg> + 'static,
    Msg: 'static, 

Much like map, but uses the TryFrom trait.

This creates a new actor reference that attempts to map from one message type to another before sending. This is useful when you need to send to different types of actors from a central location.

Notes

Errors converting from one message type to another are turned into SendErrors.

This conversion is not cheap, it requires an allocation so use with caution when it comes to performance sensitive code.

Prefer to clone an existing mapped ActorRef over creating a new one as that can reuse the allocation mentioned above.

pub fn map_fn<Msg, F>(self, map: F) -> ActorRef<Msg> where
    F: Fn(Msg) -> M + 'static,
    M: 'static, 

Change the message type of the actor reference.

Before sending the message this will first change the message into a different type using the mapping function F. This is useful when you need to send to different types of actors (using different message types) from a central location.

Notes

This conversion is not cheap, it requires an allocation so use with caution when it comes to performance sensitive code.

Prefer to clone an existing mapped ActorRef over creating a new one as that can reuse the allocation mentioned above.

pub fn try_map_fn<Msg, F, E>(self, map: F) -> ActorRef<Msg> where
    F: Fn(Msg) -> Result<M, E> + 'static,
    M: 'static, 

Change the message type of the actor reference.

Before sending the message this will first change the message into a different type using the mapping function F. This is useful when you need to send to different types of actors (using different message types) from a central location.

Notes

This conversion is not cheap, it requires an allocation so use with caution when it comes to performance sensitive code.

Prefer to clone an existing mapped ActorRef over creating a new one as that can reuse the allocation mentioned above.

pub fn join<'r>(&'r self) -> Join<'r, M>

Returns a Future that waits until the actor finishes running. Acts similar to a JoinHandle of a thread.

pub fn is_connected(&self) -> bool

Returns true if the actor to which this reference sends to is still connected.

Notes

Even if this returns true it doesn’t mean ActorRef::try_send will succeeded (even if the inbox isn’t full). There is always a race condition between using this method and doing something based on it.

This does provide one useful feature: once this returns false it will never return true again. This makes it useful in the use case where creating a message is expansive, which is wasted if the actor is no longer running. Thus this should only be used as optimisation to not do work.

pub fn sends_to<Msg>(&self, other: &ActorRef<Msg>) -> bool

Returns true if self and other send messages to the same actor.

Trait Implementations

impl<M> Clone for ActorRef<M>

fn clone(&self) -> ActorRef<M>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M> Debug for ActorRef<M>

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

Formats the value using the given formatter.

impl<M> Extend<ActorRef<M>> for ActorGroup<M>

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = ActorRef<M>>, 

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<M> From<ActorRef<M>> for ActorGroup<M>

fn from(actor_ref: ActorRef<M>) -> ActorGroup<M>

Converts to this type from the input type.

impl<M> FromIterator<ActorRef<M>> for ActorGroup<M>

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = ActorRef<M>>, 

Creates a value from an iterator.