Struct maxim::actors::Aid

pub struct Aid { /* fields omitted */ }

Encapsulates an Actor ID and is used to send messages to the actor.

This is a unique reference to the actor within the entire cluster and can be used to send messages to the actor regardless of location. The Aid does the heavy lifting of deciding where the actor is and sending the message. However it is important that the user at least has some notion of where the actor is for developing an efficient actor architecture. This aid can also be serialized to a remote system and then back to the system hosting the actor without issue. Often Aids are passed around an actor system so this is a common use case.

Methods

impl Aid

pub fn send(&self, message: Message) -> Result<(), AidError>

Attempts to send a message to the actor with the given Aid and returns std::Result::Ok when the send was successful or a std::Result::Err<MaximError> if something went wrong with the send. Note that if a user just calls send(msg).unwrap(), a panic could take down the dispatcher thread and thus eventually hang the process.

Examples

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

match aid.send(Message::new(11)) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn send_arc<T>(&self, value: Arc<T>) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

Shortcut for calling send(Message::from_arc(arc)) This method will internally wrap the Arc passed into a Message and try to send it. Note that using this method is much more efficient than send_new if you want to send an Arc that you already have. The Arc sent will be transferred to the ownership of the Aid.

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

let arc = Arc::new(11 as i32);
match aid.send_arc(arc.clone()) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn send_new<T>(&self, value: T) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

Shortcut for calling send(Message::new(value)) This method will internally wrap whatever it is passed into a Message and try to send it. This method would not be appropriate if you want to re-send a message as it would wrap the message again with the same result as if the the code called aid.send(Message::new(Message::new(value))). If the code wishes to resend a message it should just call just call send(msg).

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

match aid.send_new(11) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn send_after(
    &self,
    message: Message,
    duration: Duration
) -> Result<(), AidError>

Schedules the given message to be sent after a minimum of the specified duration. Note that Maxim doesn't guarantee that the message will be sent on exactly now + duration but rather that at least the duration will pass before the message is sent to the actor. Maxim will try to send as close as possible without going under the amount but precise timing should not be depended on. This method will return an Err if the actor has been stopped or Ok if the message was scheduled to be sent. If the actor is stopped before the duration passes then the scheduled message will never get to the actor.

Examples

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

match aid.send_after(Message::new(11), Duration::from_millis(1)) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn send_arc_after<T>(
    &self,
    value: Arc<T>,
    duration: Duration
) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

Shortcut for calling send_after(Message::from_arc(arc)) This method will internally wrap the Arc passed into a Message and try to send it. Note that using this method is much more efficient than send_new_after if you want to send an Arc that you already have.

Examples

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

let arc = Arc::new(11);
match aid.send_arc_after(arc.clone(), Duration::from_millis(1)) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn send_new_after<T>(
    &self,
    value: T,
    duration: Duration
) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

Shortcut for calling send_after(Message::new(value)) This method will internally wrap whatever it is passed into a Message and try to send it. This method would not be appropriate if you want to re-send a message as it would wrap the message again with the same result as if the the code called aid.send_after(Message::new(Message::new(value))). If the code wishes to resend a message it should just call just call send(msg).

Examples

use maxim::prelude::*;
use std::sync::Arc;
use std::time::Duration;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

let aid = system
    .spawn()
    .with(
        0 as usize,
        |state: usize, context: Context, message: Message| async move {
            if let Some(_) = message.content_as::<i32>() {
                context.system.trigger_shutdown();
            }
            Ok(Status::done(state))
       },
    )
    .unwrap();

match aid.send_new_after(11, Duration::from_millis(1)) {
    Ok(_) => println!("OK Then!"),
    Err(e) => println!("Ooops {:?}", e),
}

system.await_shutdown(None);

pub fn uuid(&self) -> Uuid

The unique UUID for this actor within the entire cluster. The UUID for an Aid is generated with a v4 random UUID so the chances of collision are not worth considering.

pub fn system_uuid(&self) -> Uuid

The unique UUID for the actor system that this actor lives on. As with uuid this value is a v4 UUID and so the chances of two systems having the same uuid is inconsequential.

pub fn name(&self) -> Option<String>

The name of the actor as assigned by the user at spawn time if any. Note that this name is guaranteed to be unique only within the actor system in which the actor was spawned; no guarantees are made that the name will be unique within a cluster of actor systems.

pub fn name_or_uuid(&self) -> String

Returns the name assigned to the Aid if it is not a None and otherwise returns the uuid of the actor as a string.

pub fn is_local(&self) -> bool

Determines if this actor lives on the local actor system or another system in the same process. Actors that are local to each other can exchange large amounts of data efficiently through passing Arcs.

pub fn sent(&self) -> Result<usize, AidError>

Determines how many messages the actor with the Aid has been sent. This method works only for local Aids, remote Aids will return an error if this is called.

pub fn received(&self) -> Result<usize, AidError>

Determines how many messages the actor with the Aid has received. This method works only for local Aids, remote Aids will return an error if this is called.

pub fn ptr_eq(left: &Aid, right: &Aid) -> bool

Checks to see if the left and right aid actually point at the exact same actor.

Trait Implementations

impl AidPool for Aid

fn send(&mut self, message: Message) -> Result<(), AidError>

See Aid::send

fn send_arc<T>(&mut self, value: Arc<T>) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

See Aid::send_arc

fn send_new<T>(&mut self, value: T) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

See Aid::send_new

fn send_after(
    &mut self,
    message: Message,
    duration: Duration
) -> Result<(), AidError>

See Aid::send_after

fn send_arc_after<T>(
    &mut self,
    value: Arc<T>,
    duration: Duration
) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

See Aid::send_arc_after

fn send_new_after<T>(
    &mut self,
    value: T,
    duration: Duration
) -> Result<(), AidError> where
    T: 'static + ActorMessage, 

See Aid::send_new_after

impl Clone for Aid

fn clone(&self) -> Aid

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Aid

fn fmt(&self, formatter: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Aid

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Display for Aid

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

Formats the value using the given formatter.

impl Eq for Aid

impl Hash for Aid

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Ord for Aid

fn cmp(&self, other: &Self) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl PartialEq<Aid> for Aid

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialOrd<Aid> for Aid

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Aid

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.