ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621545124
##########
File path: docs/_docs/key-value-api/basic-cache-operations.adoc
##########
@@ -245,18 +249,29 @@
include::code-snippets/cpp/src/cache_asynchronous_execution.cpp[tag=cache-asynch
[NOTE]
====
[discrete]
-=== Closures Execution and Thread Pools
+=== Callbacks Execution and Thread Pools
////////////////////////////////////////////////////////////////////////////////
This is java specific
////////////////////////////////////////////////////////////////////////////////
-If an asynchronous operation is completed by the time the closure is passed to
either the `IgniteFuture.listen()` or `IgniteFuture.chain()` method, then the
closure is executed synchronously by the calling thread. Otherwise, the closure
is executed asynchronously when the operation is completed.
+If an asynchronous operation is completed by the time the callback is passed
to either the `IgniteFuture.listen()` or `IgniteFuture.chain()` method, then
the callback is executed synchronously by the calling thread.
+Otherwise, the callback is executed asynchronously when the operation is
completed.
+
+Callbacks for asynchronous compute operations are called by threads from the
/perf-and-troubleshooting/thread-pools-tuning[Ignite public pool].
+Therefore, you should avoid calling synchronous cache and compute operations
from inside the callback, because it may lead to a deadlock due to pools
starvation.
+To achieve nested execution of asynchronous compute operations, you can take
advantage of
/perf-and-troubleshooting/thread-pools-tuning#creating-custom-thread-pool[custom
thread pools].
+
+Callbacks for asynchronous cache operations are called using
`IgniteConfiguration#asyncContinuationExecutor`, which defaults to
`ForkJoinPool#commonPool`.
+
+* This default executor is safe for any operations inside the callback.
+* Default behavior has changed in Ignite 2.11. Before that, async cache
operation callbacks were called from an Ignite system pool (so-called "striped
pool").
+* To restore the previous behavior, use
`IgniteConfiguration.setAsyncContinuationExecutor(Runnable::run)`.
Review comment:
Fixed
##########
File path: docs/_docs/net-specific/net-async.adoc
##########
@@ -0,0 +1,120 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+= Asynchronous APIs
+
+== Overview
+
+Many Ignite APIs have asynchronous versions, for example, `void ICache.Put`
and `Task ICache.PutAsync`.
+Async APIs allow us to write
link:https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/[efficient
non-blocking code]:
+
+[source,csharp]
+----
+ICache<int, string> cache = ignite.GetOrCreateCache<int, string>("name");
+
+// Sync, blocks thread on every call.
+cache.Put(1, "Hello");
+string hello = cache.Get(1);
+
+// Async, does not block threads.
+await cache.PutAsync(1, "Hello");
+string hello = await cache.GetAsync(1);
+----
+
+With async APIs, current thread is not blocked while we wait for the cache
operation to complete;
+it is returned to the thread pool and can perform other work.
+
+When the async operation completes, our method resumes execution - either on
the same thread, or on a different one -
+depending on the environment and the configuration. This is called "async
continuation".
+
+
+== Async Continuations
+
+Unless specified otherwise, Ignite executes async continuations on the
link:https://docs.microsoft.com/en-us/dotnet/standard/threading/the-managed-thread-pool[.NET
Thread Pool], which is safe and does not require any special care.
+
+
+=== Thin Client
+
+All thin client async APIs use
link:https://docs.microsoft.com/en-us/dotnet/standard/threading/the-managed-thread-pool[.NET
Thread Pool.] for async continuations.
+
+=== Thick Cache
+
+Server and thick client async cache APIs handle async continuations in a
special way:
+
+* In Ignite 2.11 and later, the behavior is controlled by
`IgniteConfiguration.AsyncContinuationExecutor` property. A common thread pool
is used by default, and no special care is required.
+* To restore the previous behavior, use
`IgniteConfiguration.AsyncContinuationExecutor =
AsyncContinuationExecutor.UnsafeSynchronous`.
+** Can provide a small performance improvement in some situations, because
callbacks are executed without any indirection or scheduling.
+** UNSAFE: cache operations can't proceed while system threads execute
continuations (callbacks), and deadlocks are possible if other cache operations
are invoked from the callback.
+
+[IMPORTANT]
+====
+[discrete]
+=== *Ignite 2.10 and before*: possibility of deadlocks and system pool
starvation
+
+In Ignite versions 2.10 and before, system pool is used to run async
continuations,
+which means that `GetAsync` call in the code above is executed by the system
thread.
+
+This can lead to deadlocks if user code blocks the thread, or cause starvation
because system thread is busy
+running user code instead of performing cache operations.
+
+To enable safe behavior, move continuations to the .NET Thread Pool manually:
Review comment:
Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
