You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ignite.apache.org by GitBox <gi...@apache.org> on 2021/04/27 10:35:17 UTC
[GitHub] [ignite] ptupitsyn opened a new pull request #9049: IGNITE-14609 Document old and new async continuation behavior
ptupitsyn opened a new pull request #9049:
URL: https://github.com/apache/ignite/pull/9049
Java:
* Update "Asynchronous Execution" section on "Basic Cache Operations" page
* Fix IgniteFuture javadoc (listen methods)
.NET:
* Add dedicated async page to ".NET Specific" section
* Document Cache and Compute async continuation behavior in different versions
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621535784
##########
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").
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621536752
##########
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)`.
+** Can provide a small performance improvement in some situations, because callbacks are executed without any indirection or scheduling.
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:
users@infra.apache.org
[GitHub] [ignite] IgGusev commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
IgGusev commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621098442
##########
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].
Review comment:
We should avoid using same root words if possible, it makes sentences more confusing.
Maybe replace "are called by" with use? I am not certain, because i do not quite understand conventional naming.
##########
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`.
Review comment:
Same here, calling a callback.
We should also avoid naked "using" in docs, as it leads to confusion. Replace "using" with "by using"
Please also expand "which defaults to `ForkJoinPool#commonPool`", as a new reader is not clear from the sentence what defaults to what.
##########
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.
Review comment:
We can simplify this sentence:
Calling synchronous cache and compute operations from inside the callback may lead to a deadlock due to pools starvation.
##########
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.
Review comment:
Avoid using it when you are referring to anything but the latest nown. In this case its easy to read that the operation returns to thread pool.
it -> the thread
##########
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:
To enable safe behavior, move continuations to .NET Thread Pool manually:
##########
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)`.
+** 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 callbacks, and deadlocks are possible if other cache operations are invoked from the callback.
Review comment:
We are not saving symbols, so its better to avoid contracting modal verbs.
can't -> cannot
##########
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`.
Review comment:
See comments above
##########
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").
Review comment:
Default behavior was changed in Ignite 2.11.
##########
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)`.
+** Can provide a small performance improvement in some situations, because callbacks are executed without any indirection or scheduling.
Review comment:
We need to provide some context for this statement. Also, "small improvement in some situations" is overloading the sentence on conditionals, its enough to have only one of these.
** Previous behavior can provide a small performance improvement, because callbacks are executed without any indirection or scheduling.
##########
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`.
Review comment:
I do not think "versions" is the correct term here? At the very least its confusing. Can we replace it or is it a specific term?
##########
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:
To restore previous behavior
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621542528
##########
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`.
Review comment:
Good catch, replaced with `variants`.
--
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:
users@infra.apache.org
[GitHub] [ignite] IgGusev commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
IgGusev commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621910566
##########
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`.
Review comment:
I think the text is the same as here, so they should be parralel. https://github.com/apache/ignite/pull/9049/files#diff-0f6a1ac4b53588d374bb892f4a664ef785d31ee39cadc3fb78df859fcd5dae68R268
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621527441
##########
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].
Review comment:
Replaced `called` with `invoked`
##########
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].
Review comment:
Good point, replaced `called` with `invoked`.
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn merged pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn merged pull request #9049:
URL: https://github.com/apache/ignite/pull/9049
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621528399
##########
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.
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621541155
##########
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)`.
+** 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 callbacks, and deadlocks are possible if other cache operations are invoked from the callback.
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621544754
##########
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`.
Review comment:
Please clarify, not sure which of the above applies here
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r622449371
##########
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`.
Review comment:
Fixed, thanks!
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621534352
##########
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`.
Review comment:
Reworded
--
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
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:
users@infra.apache.org
[GitHub] [ignite] ptupitsyn commented on a change in pull request #9049: IGNITE-14609 Document old and new async continuation behavior
Posted by GitBox <gi...@apache.org>.
ptupitsyn commented on a change in pull request #9049:
URL: https://github.com/apache/ignite/pull/9049#discussion_r621543210
##########
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.
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:
users@infra.apache.org