From 9113c07da54de805044db3696d6a53cf644ec9b8 Mon Sep 17 00:00:00 2001 From: Josep Prat Date: Mon, 7 Sep 2020 15:10:08 +0200 Subject: [PATCH] Add links to how to deal with blocking APIs #29544 (#29547) Refs: #29544 Adds a couple of links to dealing with blocking APIs --- akka-docs/src/main/paradox/general/actor-systems.md | 2 +- akka-docs/src/main/paradox/general/terminology.md | 4 ++++ akka-docs/src/main/paradox/typed/dispatchers.md | 1 + 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/akka-docs/src/main/paradox/general/actor-systems.md b/akka-docs/src/main/paradox/general/actor-systems.md index 1f46651025..922a1cbb09 100644 --- a/akka-docs/src/main/paradox/general/actor-systems.md +++ b/akka-docs/src/main/paradox/general/actor-systems.md @@ -75,7 +75,7 @@ a distributed application. requests) in an event-driven manner. Actors should not block (i.e. passively wait while occupying a Thread) on some external entity—which might be a lock, a network socket, etc.—unless it is unavoidable; in the latter case - see below. + see @ref:[`Blocking Needs Careful Management`](../typed/dispatchers.md#blocking-management). 2. Do not pass mutable objects between actors. In order to ensure that, prefer immutable messages. If the encapsulation of actors is broken by exposing their mutable state to the outside, you are back in normal Java concurrency diff --git a/akka-docs/src/main/paradox/general/terminology.md b/akka-docs/src/main/paradox/general/terminology.md index ebb43d9c85..a44d5bd837 100644 --- a/akka-docs/src/main/paradox/general/terminology.md +++ b/akka-docs/src/main/paradox/general/terminology.md @@ -33,6 +33,10 @@ In contrast, *non-blocking* means that no thread is able to indefinitely delay o Non-blocking operations are preferred to blocking ones, as the overall progress of the system is not trivially guaranteed when it contains blocking operations. +It's not always possible to avoid using blocking APIs, please see +@ref:[`Blocking Needs Careful Management`](../typed/dispatchers.md#blocking-management) to use those safely within the +actor code. + ## Deadlock vs. Starvation vs. Live-lock *Deadlock* arises when several participants are waiting on each other to reach a specific state to be able to progress. diff --git a/akka-docs/src/main/paradox/typed/dispatchers.md b/akka-docs/src/main/paradox/typed/dispatchers.md index deeb12d35b..dcf06cd22f 100644 --- a/akka-docs/src/main/paradox/typed/dispatchers.md +++ b/akka-docs/src/main/paradox/typed/dispatchers.md @@ -137,6 +137,7 @@ Example: configuring `internal-dispatcher` to be an alias for `default-dispatche akka.actor.internal-dispatcher = akka.actor.default-dispatcher ``` + ## Blocking Needs Careful Management In some cases it is unavoidable to do blocking operations, i.e. to put a thread