Async methods summaries

Author: alex-kulakov

Extensions/Xtensive.Orm.BulkOperations/BulkExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2019-2020 Xtensive LLC.
+// Copyright (C) 2019-2020 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 
@@ -28,6 +28,9 @@ public static int Delete<T>(this IQueryable<T> query) where T : class, IEntity =
     /// <summary>
     /// Asynchronously executes bulk delete of entities specified by the query.
     /// </summary>
+    /// <remarks>Multiple active operations in the same session instance are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
+    /// another method in this session.</remarks>
     /// <typeparam name="T">Type of the entity.</typeparam>
     /// <param name="query">The query.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
@@ -105,6 +108,9 @@ public static int Update<T>(this IQueryable<T> query, Expression<Func<T, T>> eva
     /// <summary>
     /// Asynchronously executes the UPDATE operation.
     /// </summary>
+    /// <remarks>Multiple active operations in the same session instance are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
+    /// another method in this session.</remarks>
     /// <typeparam name="T">Type of the entity.</typeparam>
     /// <param name="query">The query.</param>
     /// <param name="evaluator">The expression, that specify new values. Constructor parameters are ignored.</param>
@@ -126,6 +132,9 @@ public static int Update<T>(this IUpdatable<T> query) where T : class, IEntity =
     /// <summary>
     /// Asynchronously executes the UPDATE operation.
     /// </summary>
+    /// <remarks>Multiple active operations in the same session instance are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
+    /// another method in this session.</remarks>
     /// <typeparam name="T">Type of the entity.</typeparam>
     /// <param name="query">The query.</param>
     /// <param name="token">The cancellation token to terminate execution if necessary.</param>
@@ -151,6 +160,9 @@ public static Key Insert<T>(this QueryEndpoint queryEndpoint, Expression<Func<T>
     /// <summary>
     /// Asynchronously executes INSERT operation.
     /// </summary>
+    /// <remarks>Multiple active operations in the same session instance are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
+    /// another method in this session.</remarks>
     /// <typeparam name="T">Type of the entity.</typeparam>
     /// <param name="queryEndpoint">The query endpoint.</param>
     /// <param name="evaluator">The expression, tha specify new values.</param>

Orm/Xtensive.Orm/Core/AsyncFutureResult.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2014-2020 Xtensive LLC.
+// Copyright (C) 2014-2020 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Denis Krjuchkov

Orm/Xtensive.Orm/Core/Extensions/EnumerableExtensions.cs

@@ -486,6 +486,8 @@ public static List<TValue> SortTopologically<TValue>(this IEnumerable<TValue> va
     /// <summary>
     /// Runs delayed query as async operation or returns enumerable as a task.
     /// </summary>
+    /// <remarks>Multiple active operations are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed.</remarks>
     /// <typeparam name="T">Type of items in sequence.</typeparam>
     /// <param name="source">Delayed query sequence or regular enumerable.</param>
     /// <returns>Task that runs delayed query or completed task with source.</returns>
@@ -496,6 +498,8 @@ public static Task<IEnumerable<T>> AsAsync<T>(this IEnumerable<T> source) =>
     /// <summary>
     /// Runs delayed query as async operation or returns enumerable as a task.
     /// </summary>
+    /// <remarks>Multiple active operations are not supported. Use
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed.</remarks>
     /// <typeparam name="T">Type of items in sequence.</typeparam>
     /// <param name="source">Delayed query sequence or regular enumerable.</param>
     /// <param name="token">A token to cancel operation.</param>

Orm/Xtensive.Orm/Orm/DelayedQuery{T}.cs

@@ -30,11 +30,11 @@ public sealed class DelayedQuery<TElement> : DelayedQuery, IEnumerable<TElement>
     /// <summary>
     /// Asynchronously executes delayed query.
     /// </summary>
-    /// <param name="token">Cancellation token.</param>
-    /// <returns>Value representing query execution result.</returns>
     /// <remarks>Multiple active operations in the same session instance are not supported. Use
-    /// 'await' to ensure that any asynchronous operations have completed before calling
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
+    /// <param name="token">Cancellation token.</param>
+    /// <returns>Value representing query execution result.</returns>
     public ValueTask<QueryResult<TElement>> ExecuteAsync(CancellationToken token = default) =>
       MaterializeAsync<TElement>(token);
 

Orm/Xtensive.Orm/Orm/DelayedScalarQuery{T}.cs

@@ -31,32 +31,32 @@ public sealed class DelayedScalarQuery<TResult> : DelayedQuery
     /// <summary>
     /// Asynchronously gets value.
     /// </summary>
-    /// <returns>Task running this operation</returns>
     /// <remarks>Multiple active operations in the same session instance are not supported. Use
-    /// 'await' to ensure that any asynchronous operations have completed before calling
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
+    /// <returns>Task running this operation</returns>
     [Obsolete("AsAsync Method is obsolete. Use ExecuteAsync method instead")]
     public Task<TResult> AsAsync() => AsAsync(CancellationToken.None);
 
     /// <summary>
     /// Asynchronously gets value.
     /// </summary>
-    /// <param name="token">Token to cancel operation.</param>
-    /// <returns>Task running this operation.</returns>
     /// <remarks>Multiple active operations in the same session instance are not supported. Use
-    /// 'await' to ensure that any asynchronous operations have completed before calling
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
+    /// <param name="token">Token to cancel operation.</param>
+    /// <returns>Task running this operation.</returns>
     [Obsolete("AsAsync Method is obsolete. Use ExecuteAsync method instead")]
     public async Task<TResult> AsAsync(CancellationToken token) => await ExecuteAsync(token).ConfigureAwait(false);
 
     /// <summary>
     /// Asynchronously executes delayed scalar query.
     /// </summary>
-    /// <param name="token">Cancellation token.</param>
-    /// <returns>Value representing scalar query execution result.</returns>
     /// <remarks>Multiple active operations in the same session instance are not supported. Use
-    /// 'await' to ensure that any asynchronous operations have completed before calling
+    /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
+    /// <param name="token">Cancellation token.</param>
+    /// <returns>Value representing scalar query execution result.</returns>
     public async ValueTask<TResult> ExecuteAsync(CancellationToken token = default) =>
       (await MaterializeAsync<TResult>(token).ConfigureAwait(false)).ToScalar(resultAccessMethod);
 

Orm/Xtensive.Orm/Orm/Linq/TranslatedQuery.cs

@@ -76,6 +76,8 @@ public QueryResult<T> ExecuteSequence<T>(Session session, ParameterContext param
     /// <summary>
     /// Asynchronously executes the query in specified parameter context.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="session">The session.</param>
     /// <param name="parameterContext">The parameter context.</param>
     /// <param name="token">The token to cancel this operation</param>
@@ -90,6 +92,8 @@ public async Task<TResult> ExecuteScalarAsync<TResult>(
     /// <summary>
     /// Asynchronously executes the query in specified parameter context.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="session">The session.</param>
     /// <param name="parameterContext">The parameter context.</param>
     /// <param name="token">The token to cancel this operation</param>

Orm/Xtensive.Orm/Orm/PrefetchQuery.cs

@@ -65,14 +65,19 @@ public ExecuteAsyncResult(List<TElement> items, StrongReferenceContainer referen
     /// Asynchronously executes given <see cref="PrefetchQuery{TElement}"/> instance.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// This method internally puts all elements of the resulting sequence to a list
     /// and then it wraps mentioned list as a <see cref="QueryResult{TItem}"/>.
     /// As a consequence it is more efficient to use asynchronous enumeration over result of
     /// <see cref="AsAsyncEnumerable"/> method call because it can perform lazily
     /// not putting everything into intermediate list.
+    /// </para>
+    /// <para> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.
+    /// </para>
     /// </remarks>
-    /// <param name="token"></param>
-    /// <returns></returns>
+    /// <param name="token">The token to cancel operation if needed.</param>
+    /// <returns>A task performing operation.</returns>
     public async Task<QueryResult<TElement>> ExecuteAsync(CancellationToken token = default)
     {
       var list = new List<TElement>();

Orm/Xtensive.Orm/Orm/Providers/CommandProcessing/CommandProcessor.cs

@@ -46,6 +46,8 @@ public abstract class CommandProcessor
     /// Asynchronously executes all registered requests plus the specified one query.
     /// Default implementation is synchronous and returns complete task.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="request">The request to execute.</param>
     /// <param name="context">A contextual information to be used while executing
     /// the specified <paramref name="request"/>.</param>
@@ -72,6 +74,8 @@ public virtual Task<DataReader> ExecuteTasksWithReaderAsync(QueryRequest request
     /// <paramref name="context.AllowPartialExecution"/> argument.
     /// Default implementation executes requests synchronously and returns completed task.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="context">A contextual information to be used while executing
     /// registered query requests.</param>
     /// <param name="token">Token to cancel this operation</param>

Orm/Xtensive.Orm/Orm/Providers/Interfaces/IProviderExecutor.cs

@@ -29,6 +29,8 @@ public interface IProviderExecutor
     /// <summary>
     /// Asynchronously executes the specified request.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="request">The request to execute.</param>
     /// <param name="parameterContext"><see cref="ParameterContext"/> instance with
     /// the values of query parameters.</param>

Orm/Xtensive.Orm/Orm/Providers/Interfaces/ISqlExecutor.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2020 Xtensive LLC.
+// Copyright (C) 2012-2020 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Denis Krjuchkov
@@ -28,6 +28,8 @@ public interface ISqlExecutor
     /// Asynchronously executes the specified query statement.
     /// This method is similar to <see cref="DbCommand.ExecuteReaderAsync()"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="statement">The statement to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Result of execution.</returns>
@@ -60,6 +62,8 @@ public interface ISqlExecutor
     /// Asynchronously executes the specified scalar statement.
     /// This method is similar to <see cref="DbCommand.ExecuteScalarAsync()"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="statement">The statement to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Result of execution.</returns>
@@ -76,6 +80,8 @@ public interface ISqlExecutor
     /// Asynchronously executes the specified scalar statement.
     /// This method is similar to <see cref="DbCommand.ExecuteScalarAsync()"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="commandText">The statement to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Result of execution.</returns>
@@ -92,6 +98,8 @@ public interface ISqlExecutor
     /// Asynchronously executes the specified non query statement.
     /// This method is similar to <see cref="DbCommand.ExecuteNonQueryAsync()"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="statement">The statement to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Result of execution.</returns>
@@ -108,6 +116,8 @@ public interface ISqlExecutor
     /// Asynchronously executes the specified non query statement.
     /// This method is similar to <see cref="DbCommand.ExecuteNonQueryAsync()"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="commandText">The statement to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Result of execution.</returns>
@@ -123,6 +133,8 @@ public interface ISqlExecutor
     /// Asynchronously executes group of DDL statements
     /// via <see cref="ExecuteNonQueryAsync(System.String, System.Threading.CancellationToken)"/>.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <param name="statements">Statements to execute</param>
     Task ExecuteManyAsync(IEnumerable<string> statements, CancellationToken token = default);
@@ -137,6 +149,8 @@ public interface ISqlExecutor
     /// <summary>
     /// Asynchronously executes the specified extraction tasks.
     /// </summary>
+    /// <remarks> Multiple active operations are not supported. Use <see langword="await"/>
+    /// to ensure that all asynchronous operations have completed.</remarks>
     /// <param name="tasks">Tasks to execute.</param>
     /// <param name="token">The cancellation token to terminate execution if needed.</param>
     /// <returns>Extraction result.</returns>