Struct kompact::messaging::NetMessage

pub struct NetMessage {
    pub sender: ActorPath,
    pub receiver: ActorPath,
    pub data: NetData,
}

An incoming message from the networking subsystem

Provides actor paths for the sender of the message and the receiver in addition to the actual data.

It is recommend to use try_deserialise or try_deserialise_unchecked to unpack the contained data to the appropriate type. These methods abstract over whether or not the data is actually serialised or simply heap-allocated.

Fields

sender: ActorPath

The sender of the message

More concretely, this is the actor path that was supplied as a source by the original sender.

receiver: ActorPath

The receiver of the message

More concretely, this is the actor path that was used as a destination for the message. In particular, of the message was sent to a named path for the current component, instead of the unique path, then this will be the named path.

data: NetData

The actual data of the message

Implementations

impl NetMessage

pub fn with_box(
    ser_id: SerId,
    sender: ActorPath,
    receiver: ActorPath,
    data: Box<dyn Serialisable>
) -> NetMessage

Create a network message with heap-allocated data

pub fn with_bytes(
    ser_id: SerId,
    sender: ActorPath,
    receiver: ActorPath,
    data: Bytes
) -> NetMessage

Create a network message with serialised data

pub fn with_chunk_lease(
    ser_id: SerId,
    sender: ActorPath,
    receiver: ActorPath,
    data: ChunkLease
) -> NetMessage

Create a network message with a ChunkLease, pooled buffers. For outgoing network messages the data inside the data should be both serialised and (framed)crate::net::frames.

pub fn with_chunk_ref(
    ser_id: SerId,
    sender: ActorPath,
    receiver: ActorPath,
    data: ChunkRef
) -> NetMessage

Create a network message with a ChunkLease, pooled buffers. For outgoing network messages the data inside the data should be both serialised and (framed)crate::net::frames.

pub fn sender(&self) -> &ActorPath

Return a reference to the sender field

pub fn try_into_deserialised<T: 'static, D>(
    self
) -> Result<DeserialisedMessage<T>, UnpackError<Self>> where
    D: Deserialiser<T>, 

Try to deserialise the data into a value of type T wrapped into a message

This method attempts to deserialise the contents into an instance of T using the deserialiser D. It will only do so after verifying that ser_id == D::SER_ID.

If the serialisation id does not match, this message is returned unaltered wrapped in an UnpackError.

Example

use kompact::prelude::*;
use bytes::BytesMut;


let test_str = "Test me".to_string();
// serialise the string
let mut mbuf = BytesMut::with_capacity(test_str.size_hint().expect("size hint"));
test_str.serialise(&mut mbuf).expect("serialise");
// create a net message
let buf = mbuf.freeze();
let msg = NetMessage::with_bytes(String::SER_ID, some_path, some_path2, buf);
// try to deserialise it again
match msg.try_into_deserialised::<u64, u64>() {
    Ok(_) => unreachable!("It's definitely not a u64..."),
    Err(UnpackError::NoIdMatch(msg_again)) => {
        match msg_again.try_into_deserialised::<String, String>() {
            Ok(test_msg) => assert_eq!(test_str, test_msg.content),
            Err(_) => unreachable!("It's definitely a string..."),
        }   
    }
    Err(error) => panic!("Not the error we expected: {:?}", error),  
}

pub fn try_deserialise<T: 'static, D>(self) -> Result<T, UnpackError<Self>> where
    D: Deserialiser<T>, 

Try to deserialise the data into a value of type T

This method attempts to deserialise the contents into an instance of T using the deserialiser D. It will only do so after verifying that ser_id == D::SER_ID.

If the serialisation id does not match, this message is returned unaltered wrapped in an UnpackError.

Example

use kompact::prelude::*;
use bytes::BytesMut;


let test_str = "Test me".to_string();
// serialise the string
let mut mbuf = BytesMut::with_capacity(test_str.size_hint().expect("size hint"));
test_str.serialise(&mut mbuf).expect("serialise");
// create a net message
let buf = mbuf.freeze();
let msg = NetMessage::with_bytes(String::SER_ID, some_path, some_path2, buf);
// try to deserialise it again
match msg.try_deserialise::<u64, u64>() {
    Ok(_) => unreachable!("It's definitely not a u64..."),
    Err(UnpackError::NoIdMatch(msg_again)) => {
        match msg_again.try_deserialise::<String, String>() {
            Ok(test_res) => assert_eq!(test_str, test_res),
            Err(_) => unreachable!("It's definitely a string..."),
        }   
    }
    Err(error) => panic!("Not the error we expected: {:?}", error),  
}

Note

If you need the sender or the receiver to be owned after deserialisation, either use msg.data.try_deserialise<...>(...) instead, or use try_into_deserialised.

pub fn try_deserialise_unchecked<T: 'static, D>(
    self
) -> Result<T, UnpackError<Self>> where
    D: Deserialiser<T>, 

Try to deserialise the data into a value of type T

This method attempts to deserialise the contents into an instance of T using the deserialiser D without checking the ser_id first for a match.

Only use this, if you have already verified that ser_id == D::SER_ID! Otherwise use try_deserialise.

Example

use kompact::prelude::*;
use bytes::BytesMut;


let test_str = "Test me".to_string();
// serialise the string
let mut mbuf = BytesMut::with_capacity(test_str.size_hint().expect("size hint"));
test_str.serialise(&mut mbuf).expect("serialise");
// create a net message
let buf = mbuf.freeze();
let msg = NetMessage::with_bytes(String::SER_ID, some_path, some_path2, buf);
// try to deserialise it again
match msg.ser_id() {
    &u64::SER_ID => unreachable!("It's definitely not a u64..."),
    &String::SER_ID => {
        let test_res = msg.try_deserialise_unchecked::<String, String>().expect("deserialised");
        assert_eq!(test_str, test_res);
    }
    _ => unreachable!("It's definitely not...whatever this is..."),
}

Note

The match_deser macro generates code that is approximately equivalent to the example above with some nicer syntax.

If you need the sender or the receiver to be owned after deserialisation, either use msg.data.try_deserialise_unchecked<...>(...) instead, or use try_into_deserialised.

pub fn ser_id(&self) -> &SerId

Returns a reference to the serialisation id of this message

Trait Implementations

impl Debug for NetMessage

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

Formats the value using the given formatter.

impl RoutingPolicy<DynActorRef, NetMessage> for RoundRobinRouting

fn route(
    &self,
    members: &[&DynActorRef],
    msg: NetMessage,
    logger: &KompactLogger
)

Route the msg to the appropriate members

fn boxed_clone(
    &self
) -> Box<dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync>

Create a boxed copy of this policy

fn broadcast(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the broadcast part of this policy, if any

fn select(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the select part of this policy, if any

impl<H: BuildHasher + Clone + Send + Sync + 'static> RoutingPolicy<DynActorRef, NetMessage> for SenderHashBucketRouting<H>

fn route(
    &self,
    members: &[&DynActorRef],
    msg: NetMessage,
    logger: &KompactLogger
)

Route the msg to the appropriate members

fn boxed_clone(
    &self
) -> Box<dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync>

Create a boxed copy of this policy

fn broadcast(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the broadcast part of this policy, if any

fn select(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the select part of this policy, if any

impl RoutingPolicy<DynActorRef, NetMessage> for BroadcastRouting

fn route(
    &self,
    members: &[&DynActorRef],
    msg: NetMessage,
    logger: &KompactLogger
)

Route the msg to the appropriate members

fn boxed_clone(
    &self
) -> Box<dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync>

Create a boxed copy of this policy

fn broadcast(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the broadcast part of this policy, if any

fn select(
    &self
) -> Option<&(dyn RoutingPolicy<DynActorRef, NetMessage> + Send + Sync)>

Provide the select part of this policy, if any

impl Sink<NetMessage> for DynActorRef

Helper for forwarding MsgEnvelopes to actor references

type Error = ()

The type of value produced by the sink when an error occurs.

fn poll_ready(
    self: Pin<&mut Self>,
    _cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, item: NetMessage) -> Result<(), Self::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

fn poll_flush(
    self: Pin<&mut Self>,
    _cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>

Flush any remaining output from this sink.

fn poll_close(
    self: Pin<&mut Self>,
    _cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>

Flush any remaining output and close this sink, if necessary.

impl TryClone for NetMessage

fn try_clone(&self) -> Result<Self, SerError>

Tries to produce a copy of self or returns an error