pub struct Context<C = (), K = Singleton> { /* private fields */ }
Expand description
An actor execution context.
Implementations§
source§impl<C, K> Context<C, K>
impl<C, K> Context<C, K>
sourcepub fn attach<S1: SourceHandle>(&mut self, source: UnattachedSource<S1>) -> S1
pub fn attach<S1: SourceHandle>(&mut self, source: UnattachedSource<S1>) -> S1
Attaches the provided source to the context.
sourcepub fn set_status(&self, status: ActorStatus)
pub fn set_status(&self, status: ActorStatus)
Updates the actor’s status.
§Example
ctx.set_status(elfo::ActorStatus::ALARMING.with_details("something wrong"));
sourcepub fn set_restart_policy(&self, policy: impl Into<Option<RestartPolicy>>)
pub fn set_restart_policy(&self, policy: impl Into<Option<RestartPolicy>>)
Overrides the group’s default restart policy.
Note: after restart the actor will be created from scratch, so this override will be also reset to the group’s default restart policy.
§Example
// Override the group's default restart policy.
ctx.set_restart_policy(elfo::RestartPolicy::never());
// Set the group's default restart policy.
ctx.set_restart_policy(None);
sourcepub fn close(&self) -> bool
pub fn close(&self) -> bool
Closes the mailbox, that leads to returning None
from recv()
and
try_recv()
after handling all available messages in the mailbox.
Returns true
if the mailbox has just been closed.
sourcepub async fn send<M: Message>(&self, message: M) -> Result<(), SendError<M>>
pub async fn send<M: Message>(&self, message: M) -> Result<(), SendError<M>>
Sends a message using the routing system.
Returns Err
if the message hasn’t reached any mailboxes.
§Example
// Fire and forget.
let _ = ctx.send(SomethingHappened).await;
// Fire or fail.
ctx.send(SomethingHappened).await?;
// Fire or log.
if let Ok(err) = ctx.send(SomethingHappened).await {
warn!("...", error = err);
}
sourcepub fn try_send<M: Message>(&self, message: M) -> Result<(), TrySendError<M>>
pub fn try_send<M: Message>(&self, message: M) -> Result<(), TrySendError<M>>
Tries to send a message using the routing system.
Returns
Ok(())
if the message has been added to any mailbox.Err(Full(_))
if some mailboxes are full.Err(Closed(_))
otherwise.
§Example
// Fire and forget.
let _ = ctx.try_send(SomethingHappened);
// Fire or fail.
ctx.try_send(SomethingHappened)?;
// Fire or log.
if let Err(err) = ctx.try_send(SomethingHappened) {
warn!("...", error = err);
}
sourcepub fn request<R: Request>(
&self,
request: R
) -> RequestBuilder<'_, C, K, R, Any>
pub fn request<R: Request>( &self, request: R ) -> RequestBuilder<'_, C, K, R, Any>
sourcepub fn request_to<R: Request>(
&self,
recipient: Addr,
request: R
) -> RequestBuilder<'_, C, K, R, Any>
pub fn request_to<R: Request>( &self, recipient: Addr, request: R ) -> RequestBuilder<'_, C, K, R, Any>
sourcepub async fn send_to<M: Message>(
&self,
recipient: Addr,
message: M
) -> Result<(), SendError<M>>
pub async fn send_to<M: Message>( &self, recipient: Addr, message: M ) -> Result<(), SendError<M>>
Sends a message to the specified recipient.
Returns Err
if the message hasn’t reached any mailboxes.
§Example
// Fire and forget.
let _ = ctx.send_to(addr, SomethingHappened).await;
// Fire or fail.
ctx.send_to(addr, SomethingHappened).await?;
// Fire or log.
if let Some(err) = ctx.send_to(addr, SomethingHappened).await {
warn!("...", error = err);
}
sourcepub fn try_send_to<M: Message>(
&self,
recipient: Addr,
message: M
) -> Result<(), TrySendError<M>>
pub fn try_send_to<M: Message>( &self, recipient: Addr, message: M ) -> Result<(), TrySendError<M>>
Tries to send a message to the specified recipient.
Returns Err
if the message hasn’t reached mailboxes or they are full.
§Example
// Fire and forget.
let _ = ctx.try_send_to(addr, SomethingHappened);
// Fire or fail.
ctx.try_send_to(addr, SomethingHappened)?;
// Fire or log.
if let Some(err) = ctx.try_send_to(addr, SomethingHappened) {
warn!("...", error = err);
}
sourcepub fn respond<R: Request>(&self, token: ResponseToken<R>, message: R::Response)
pub fn respond<R: Request>(&self, token: ResponseToken<R>, message: R::Response)
Responds to the requester with the provided response.
The token can be used only once.
msg!(match envelope {
(SomeRequest, token) => {
ctx.respond(token, SomeResponse);
}
})
sourcepub async fn recv(&mut self) -> Option<Envelope>where
C: 'static,
pub async fn recv(&mut self) -> Option<Envelope>where
C: 'static,
Receives the next envelope from the mailbox or sources.
If the envelope isn’t available, the method waits for the next one.
If the mailbox is closed, None
is returned.
§Budget
The method returns the execution back to the runtime once the actor’s
budget has been exhausted. It prevents the actor from blocking the
runtime for too long. See coop
for details.
§Cancel safety
This method is cancel safe. However, using select!
requires handling
tracing on your own, so avoid it if possible (use sources instead).
§Panics
If the method is called again after None
is returned.
§Example
while let Some(envelope) = ctx.recv().await {
msg!(match envelope {
SomethingHappened => { /* ... */ },
});
}
sourcepub async fn try_recv(&mut self) -> Result<Envelope, TryRecvError>where
C: 'static,
pub async fn try_recv(&mut self) -> Result<Envelope, TryRecvError>where
C: 'static,
Receives the next envelope from the mailbox or sources without waiting.
If the envelope isn’t available, Err(TryRecvError::Empty)
is returned.
If the mailbox is closed, Err(TryRecvError::Closed)
is returned.
Useful to batch message processing.
The method is async due to the following reasons:
- To poll sources, not only the mailbox.
- To respect the actor budget (see below).
§Budget
The method returns the execution back to the runtime once the actor’s
budget has been exhausted. It prevents the actor from blocking the
runtime for too long. See coop
for details.
§Cancel safety
This method is cancel safe. However, using select!
requires handling
tracing on your own, so avoid it if possible (use sources instead).
§Panics
If the method is called again after Err(TryRecvError::Closed)
.
§Example
Handle all available messages:
let mut batch = Vec::new();
loop {
match ctx.try_recv().await {
Ok(envelope) => batch.push(envelope),
Err(err) => {
handle_batch(batch.drain(..));
if err.is_empty() {
// Wait for the next batch.
if let Some(envelope) = ctx.recv().await {
batch.push(envelope);
continue;
}
}
break;
},
}
}
sourcepub fn start_info(&self) -> &ActorStartInfo
pub fn start_info(&self) -> &ActorStartInfo
Retrieves information related to the start of the actor.
§Panics
This method will panic if the context is pruned, indicating that the required information is no longer available.
§Example
match ctx.start_info().cause {
ActorStartCause::GroupMounted => {
// The actor started because its group was mounted.
}
ActorStartCause::OnMessage => {
// The actor started in response to a message.
}
ActorStartCause::Restarted => {
// The actor started due to the restart policy.
}
_ => {}
}
sourcepub fn unpack_config<'c>(&self, config: &'c AnyConfig) -> &'c Cwhere
C: for<'de> Deserialize<'de> + 'static,
pub fn unpack_config<'c>(&self, config: &'c AnyConfig) -> &'c Cwhere
C: for<'de> Deserialize<'de> + 'static,
Used to get the typed config from ValidateConfig
.
msg!(match envelope {
(ValidateConfig { config, .. }, token) => {
let new_config = ctx.unpack_config(&config);
ctx.respond(token, Err("oops".into()));
}
})