Requests Overview

In the context of the Kameo, requests are the means through which actors communicate and interact with each other. These interactions are encapsulated in two primary forms: ask requests and tell requests. Understanding the nuances between these two types of requests is crucial for effectively managing actor behaviors and ensuring the robustness of your application.

Ask Requests

Ask requests are a form of message sending where the sender waits for a response from the receiver. This pattern is useful when the sender requires data or confirmation that an action has been completed before proceeding. Unlike tell requests, ask requests inherently support handling responses and errors, providing a direct way to deal with exceptional conditions.

Key Features of Ask Requests:

Reply Awaited: The sender pauses its execution and waits for a reply, making it synchronous in nature within an asynchronous execution model.
Error Handling: If an actor encounters an error while processing an ask request, the responsibility of handling these errors falls to the caller. This allows for more granular error management strategies.
Timeouts:
- Mailbox Timeout: For actors with a bounded mailbox, an optional mailbox_timeout can be specified. This timeout represents the maximum duration the request will wait in the queue before being processed. If the mailbox is full beyond this duration, the request may be dropped or an error returned.
- Reply Timeout: A reply_timeout can also be set, indicating how long the sender will wait for a response. This is particularly useful for avoiding indefinite blocking in scenarios where the receiver might be unable to process the request promptly.

Tell Requests

Tell requests, on the other hand, are the "fire-and-forget" type of messages. When a tell request is sent, the sender does not wait for any acknowledgment or reply from the receiver. This approach is ideal for notifications or commands where the outcome does not directly influence the sender's immediate actions.

Characteristics of Tell Requests:

No Reply: The sender continues its execution without waiting for a response, embodying a truly asynchronous interaction pattern.
Error Handling: Errors encountered by the actor while processing a tell request are treated as panics. By default, such panics may lead to the stopping of the actor, although this behavior can be customized via the Actor::on_panic hook to allow for error recovery or logging.
Mailbox Timeout: Similar to ask requests, a mailbox_timeout can be set for tell requests sent to actors with bounded mailboxes. This timeout helps manage the queuing behavior in scenarios where the actor's mailbox might be at capacity, ensuring that the system can gracefully handle backpressure.

Request Methods

Sending a message can be done using one of the traits/methods listed in this table. Each cell describes the behaviour of the implementation depending on the mailbox type.

The column headings describe the following:

Ask (bounded): refers to sending a message using ask on an actor with a BoundedMailbox.
Ask (unbounded): refers to sending a message using ask on an actor with an UnboundedMailbox.
Tell (bounded): refers to sending a message using tell on an actor with a BoundedMailbox.
Tell (unbounded): refers to sending a message using tell on an actor with an UnboundedMailbox.

Trait :: Method	Ask (bounded)	Ask (unbounded)	Tell (bounded)	Tell (unbounded)
`MessageSend` :: `send`	Sends a message, waiting for mailbox capacity and a reply.	Sends a message, waiting for a reply.	Sends a message, waiting for mailbox capacity.	Sends a message.
`MessageSendSync` :: `send_sync`	❌	❌	❌	Sends a message synchronously.
`TryMessageSend` :: `try_send`	Tries to send a message, waiting for a reply but failing if the mailbox is full.	Send a message, waiting for a reply.	Tries to send a message, but failing if the mailbox is full.	Sends a message.
`TryMessageSendSync` :: `try_send_sync`	❌	❌	Tries to send a message synchronously, but failing if the mailbox is full.	Sends a message synchronously.
`BlockingMessageSend` :: `blocking_send`	Sends a message, blocking the thread while waiting for mailbox capacity and a reply.	Sends a message, blocking the thread while waiting for a reply.	Sends a message, blocking the thread while waiting for mailbox capacity.	Sends a message.
`TryBlockingMessageSend` :: `try_blocking_send`	Tries to send a message, blocking the thread while waiting for a reply, but failing if the mailbox is full.	Tries to send a message, blocking the thread while waiting for a reply.	Tries to send a message, failing if the mailbox is full.	Sends a message.
`ForwardMessageSend` :: `forward`	Sends a message, waiting for mailbox capacity with the reply being forwarded to a provided ReplySender.	Sends a message, with the reply being forwarded to a provided ReplySender.	❌	❌

Supported Requests

Depending on whether a message is being sent with a timeout set or to a remote actor, some methods may not be available. Below is table showing which methods are available under different circumstances.


Method	Ask (bounded)	Ask (unbounded)	Tell (bounded)	Tell (unbounded)
`send`	✅ 📬 ⏳ 🌐	✅ ⏳ 🌐	✅ 📬 🌐	✅ 🌐
`send_sync`	❌	❌	❌	✅
`try_send`	✅ ⏳ 🌐	✅ ⏳ 🌐	✅ 🌐	✅ 🌐
`try_send_sync`	❌	❌	✅	✅
`blocking_send`	✅	✅	✅	✅
`try_blocking_send`	✅	✅	✅	✅
`forward`	✅ 📬	✅	❌	❌

Legend

✅ Supported: Supported for local actors with no timeouts set
📬 With mailbox timeout: Supported for local actors with a mailbox timeout set
⏳ With reply timeout: Supported for local actors with a reply timeout set
🌐 Remote: Supported for remote actor messaging
❌ Unsupported

Summary

Requests, encompassing both the ask and tell patterns, offer versatile communication strategies within Kameo. This duality provides the flexibility to either await responses for critical operations or to proceed without direct feedback for more autonomous actions. Such versatility is key to supporting a broad spectrum of application requirements, from straightforward notifications to intricate data exchanges and control flows, enhancing the dynamism and efficiency of your actor interactions.

Getting Started