(pekko) branch main updated: Improve StatusReply Scaladoc: clarify serialization implications (#2811)

[he...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hepin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git


The following commit(s) were added to refs/heads/main by this push:
     new 307a6db900 Improve StatusReply Scaladoc: clarify serialization implications (#2811)
307a6db900 is described below

commit 307a6db9006134610e9d15e3d08bfc0b0b35b78e
Author: He-Pin(kerr) <he...@gmail.com>
AuthorDate: Sat Mar 28 17:25:30 2026 +0800

    Improve StatusReply Scaladoc: clarify serialization implications (#2811)
---
 .../main/scala/org/apache/pekko/pattern/StatusReply.scala  | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/actor/src/main/scala/org/apache/pekko/pattern/StatusReply.scala b/actor/src/main/scala/org/apache/pekko/pattern/StatusReply.scala
index c8a294cec2..a359038d78 100644
--- a/actor/src/main/scala/org/apache/pekko/pattern/StatusReply.scala
+++ b/actor/src/main/scala/org/apache/pekko/pattern/StatusReply.scala
@@ -109,6 +109,8 @@ object StatusReply {
    * Scala API: Turn a [[scala.util.Try]] into a status reply.
    *
    * Transforms exceptions into status reply errors containing just the exception message string.
+   * This makes it safe for use with remote actors since Pekko includes built-in serializers
+   * for text-based error messages, unlike arbitrary exception types.
    *
    * See [[#fromTryKeepException]] for passing the exception along as is.
    *
@@ -120,14 +122,14 @@ object StatusReply {
   }
 
   /**
-   * Scala API: Turn a [[scala.util.Try]] into a status reply.
+   * Scala API: Turn a [[scala.util.Try]] into a status reply, keeping the original exception.
    *
-   * Prefer the string based error response over this one when possible to avoid tightly coupled logic across
-   * actors and passing internal failure details on to callers that can not do much to handle them. [[#fromTry]]
-   * provides a convenience factory doing that for [[scala.util.Try]].
+   * Unlike [[#fromTry]], this preserves the full exception object. This is useful when callers
+   * need to match on exception types, but requires that serializers are configured for the
+   * exception types used when communicating with remote actors.
    *
-   * For cases where types are needed to identify errors and behave differently enumerating them with a specific
-   * set of response messages may be a better alternative to encoding them as generic exceptions.
+   * Prefer [[#fromTry]] (string-based errors) when possible to avoid tightly coupled logic across
+   * actors and passing internal failure details on to callers that can not do much to handle them.
    *
    * Also note that Pekko does not contain pre-built serializers for arbitrary exceptions.
    *


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org