PipeTo

Overview

The PipeTo and PipeToName methods are designed to handle cases where an actor needs to interact with an external service or perform a long-running task asynchronously. Instead of blocking its mailbox while waiting for a task to complete, an actor can launch the task and then “pipe” its successful result to the intended recipient’s mailbox as a message to process. This approach keeps the actor responsive and maintains the single-threaded execution guarantee of actor message processing. These methods are available on the actor reference PID as well as on the ReceiveContext(a.k.a message context).

By integrating the PipeTo and PipeToName feature into your actor workflows, you can seamlessly combine asynchronous operations with the actor message-processing model, ensuring high throughput and responsiveness even when dealing with external or long-running tasks.

Options

When using the piping mechanism, you can configure the following options:

• WithTimeout – Specifies the maximum duration to wait for the long-running task to complete before timing out.

• WithCircuitBreaker – Defines the circuit breaker policy to apply while waiting for the long-running task, adding resilience against repeated failures.

Purpose and Use Cases

Use the PipeTo feature when:

• Integrating External Services: When an actor makes an asynchronous call to an external API or service, the future result (task) can be piped to itself or another actor for further processing.

• Non-blocking Asynchronous Processing: Avoids blocking the actor’s message loop by offloading the waiting for task completion to a separate goroutine.

• Decoupled Response Handling: The asynchronous task’s result is delivered as a message to the target actor’s mailbox, making it part of the actor’s regular message-processing flow.

Note

The key distinction between PipeTo and PipeToName is that PipeToName introduces location transparency. While both are used to pipe the success result of a long-running task to an actor, PipeToName allows you to target the actor by name rather than by direct reference—making it resilient to changes in where or how the actor is hosted.