Struct Messages 

pub struct Messages<M>
where
    M: Message,
{ /* private fields */ }

A message collection that represents the messages that occurred within the last two Messages::update calls. Messages can be written to using a MessageWriter and are typically cheaply read using a MessageReader.

Each message can be consumed by multiple systems, in parallel, with consumption tracked by the MessageReader on a per-system basis.

If no ordering is applied between writing and reading systems, there is a risk of a race condition. This means that whether the messages arrive before or after the next Messages::update is unpredictable.

This collection is meant to be paired with a system that calls Messages::update exactly once per update/frame.

message_update_system is a system that does this, typically initialized automatically using add_message. MessageReaders are expected to read messages from this collection at least once per loop/frame. Messages will persist across a single frame boundary and so ordering of message producers and consumers is not critical (although poorly-planned ordering may cause accumulating lag). If messages are not handled by the end of the frame after they are updated, they will be dropped silently.

Example

use bevy_ecs::message::{Message, Messages};

#[derive(Message)]
struct MyMessage {
    value: usize
}

// setup
let mut messages = Messages::<MyMessage>::default();
let mut cursor = messages.get_cursor();

// run this once per update/frame
messages.update();

// somewhere else: write a message
messages.write(MyMessage { value: 1 });

// somewhere else: read the messages
for message in cursor.read(&messages) {
    assert_eq!(message.value, 1)
}

// messages are only processed once per reader
assert_eq!(cursor.read(&messages).count(), 0);

Details

Messages is implemented using a variation of a double buffer strategy. Each call to update swaps buffers and clears out the oldest one.

• MessageReaders will read messages from both buffers.
• MessageReaders that read at least once per update will never drop messages.
• MessageReaders that read once within two updates might still receive some messages
• MessageReaders that read after two updates are guaranteed to drop all messages that occurred before those updates.

The buffers in Messages will grow indefinitely if update is never called.

An alternative call pattern would be to call update manually across frames to control when messages are cleared. This complicates consumption and risks ever-expanding memory usage if not cleaned up, but can be done by adding your message as a resource instead of using add_message.

Example usage. Example usage standalone.

Implementations

impl<M> Messages<M>

where M: Message,

pub fn oldest_message_count(&self) -> usize

Returns the index of the oldest message stored in the message buffer.

pub fn write(&mut self, message: M) -> MessageId<M>

Writes an message to the current message buffer. MessageReaders can then read the message. This method returns the ID of the written message.

pub fn write_batch( &mut self, messages: impl IntoIterator<Item = M>, ) -> WriteBatchIds<M>

Writes a list of messages all at once, which can later be read by MessageReaders. This is more efficient than writing each message individually. This method returns the IDs of the written messages.

pub fn write_default(&mut self) -> MessageId<M>

where M: Default,

Writes the default value of the message. Useful when the message is an empty struct. This method returns the ID of the written message.

pub fn get_cursor(&self) -> MessageCursor<M>

Gets a new MessageCursor. This will include all messages already in the message buffers.

pub fn get_cursor_current(&self) -> MessageCursor<M>

Gets a new MessageCursor. This will ignore all messages already in the message buffers. It will read all future messages.

pub fn update(&mut self)

Swaps the message buffers and clears the oldest message buffer. In general, this should be called once per frame/update.

If you need access to the messages that were removed, consider using Messages::update_drain.

pub fn update_drain(&mut self) -> impl Iterator<Item = M>

Swaps the message buffers and drains the oldest message buffer, returning an iterator of all messages that were removed. In general, this should be called once per frame/update.

If you do not need to take ownership of the removed messages, use Messages::update instead.

pub fn clear(&mut self)

Removes all messages.

pub fn len(&self) -> usize

Returns the number of messages currently stored in the message buffer.

pub fn is_empty(&self) -> bool

Returns true if there are no messages currently stored in the message buffer.

pub fn drain(&mut self) -> impl Iterator<Item = M>

Creates a draining iterator that removes all messages.

pub fn iter_current_update_messages(&self) -> impl ExactSizeIterator

Iterates over messages that happened since the last “update” call. WARNING: You probably don’t want to use this call. In most cases you should use an MessageReader. You should only use this if you know you only need to consume messages between the last update() call and your call to iter_current_update_messages. If messages happen outside that window, they will not be handled. For example, any messages that happen after this call and before the next update() call will be dropped.

pub fn get_message(&self, id: usize) -> Option<(&M, MessageId<M>)>

Get a specific message by id if it still exists in the messages buffer.

Trait Implementations

impl<M> Component for Messages<M>

where M: Message, Messages<M>: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Messages<M>>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_discard ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl<M> Debug for Messages<M>

where M: Debug + Message,

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

Formats the value using the given formatter.

impl<M> Default for Messages<M>

where M: Message,

fn default() -> Messages<M>

Returns the “default value” for a type.

impl<M> Extend<M> for Messages<M>

where M: Message,

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = 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> FromReflect for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &(dyn PartialReflect + 'static)) -> Option<Messages<M>>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<M> GetTypeRegistration for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default [TypeRegistration] for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<M> PartialReflect for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the [TypeInfo] of the type represented by this value.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Messages<M>>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Messages<M>>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Messages<M>>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_partial_cmp( &self, value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing [PartialReflect], combines reflect_clone and take in a useful fashion, automatically constructing an appropriate [ReflectCloneError] if the downcast fails.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

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

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<M> Reflect for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<Messages<M>>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Messages<M>>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl<M> Struct for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, name: &str) -> Option<&(dyn PartialReflect + 'static)>

Gets a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut( &mut self, name: &str, ) -> Option<&mut (dyn PartialReflect + 'static)>

Gets a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

fn field_at(&self, index: usize) -> Option<&(dyn PartialReflect + 'static)>

Gets a reference to the value of the field with index index as a &dyn PartialReflect.

fn field_at_mut( &mut self, index: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

Gets a mutable reference to the value of the field with index index as a &mut dyn PartialReflect.

fn name_at(&self, index: usize) -> Option<&str>

Gets the name of the field with index index.

fn index_of_name(&self, name: &str) -> Option<usize>

Gets the index of the field with the given name.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn to_dynamic_struct(&self) -> DynamicStruct

Creates a new [DynamicStruct] from this struct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if [TypeInfo] is not available.

impl<M> TypePath for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<M> Typed for Messages<M>

where M: Message + TypePath, Messages<M>: Any + Send + Sync, MessageSequence<M>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<M> Resource for Messages<M>

where M: Message, Messages<M>: Send + Sync + 'static,