From bb69cb2f8ec8ffc773a6917f0430220cda19f8f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?=
 <12201973+fredericDelaporte@users.noreply.github.com>
Date: Fri, 6 Jul 2018 14:20:18 +0200
Subject: [PATCH 1/2] Document future results

---
 doc/reference/modules/performance.xml | 63 +++++++++++++++++++++++++++
 doc/reference/modules/query_linq.xml  |  7 +--
 2 files changed, 65 insertions(+), 5 deletions(-)

diff --git a/doc/reference/modules/performance.xml b/doc/reference/modules/performance.xml
index bdaa4344044..53578f36591 100644
--- a/doc/reference/modules/performance.xml
+++ b/doc/reference/modules/performance.xml
@@ -1342,4 +1342,67 @@ ICollection<Policy> policies = CollectionHelper.ToArray<Policy>(results[1]);]]><
           perform additional logic (getting the policies of the customers we are associated with), all in a single database round-trip.
         </para>
     </sect1>
+
+     <sect1 id="performance-future">
+        <title>Future results</title>
+
+        <para>
+            Queries can be converted to future results instead of being directly executed. Future
+            results are not evaluated till one gets executed. At that point, all defined future
+            results are evaluated in one single round-trip to the database.
+        </para>
+
+        <para>
+            Future results are an alternative to using <xref linkend="performance-multi-query"/>.
+            They avoid the need to explicitly regroup queries, but they also hides which queries will
+            get executed: any pending future results of the session will be batched together, no
+            matter where they were defined, included out-of-scope pending future results.
+        </para>
+
+        <para>
+            Future results are obtained by calling <literal>Future</literal> or
+            <literal>FutureValue</literal> methods of a HQL, Criteria, QueryOver or SQL query.
+            For LINQ queries, the methods are named <literal>ToFuture</literal> and
+            <literal>ToFutureValue</literal>, see <xref linkend="querylinq-futureresults"/> for
+            an example.
+        </para>
+
+        <programlisting><![CDATA[// Define queries
+IFutureEnumerable<Cat> cats =
+    session.CreateQuery("from Cat c where c.Color = :color")
+        .SetString("color", "black")
+        .Future();
+IFutureValue<int> catCount =
+    session.QueryOver<Cat>()
+        .ToRowCountQuery()
+        .FutureValue<int>();
+// Execute them
+foreach(Cat cat in cats.GetEnumerable())
+{
+    // Do something
+}
+if (catCount.Value > 10)
+{
+    // Do something
+}
+]]></programlisting>
+
+        <para>
+            In the above example, accessing <literal>catCount.Value</literal> does not trigger a round-trip
+            to the database: it has been evaluated with <literal>cats.GetEnumerable()</literal> call. If
+            instead <literal>catCount.Value</literal> was accessed first, it would have executed both
+            future results and <literal>cats.GetEnumerable()</literal> would not have triggered a round-trip
+            to the database.
+        </para>
+
+        <para>
+            As showcased in the previous example, <literal>Future</literal> allows to get a future enumerable
+            result, and <literal>FutureValue</literal> is meant to obtain a single value result.
+        </para>
+
+        <para>
+            Note: in NHibernate v5.1 and previous versions, Criteria/QueryOver future results were batched
+            separately. Since NHibernate v5.2, they are batched with other querying API future results.
+        </para>
+    </sect1>
 </chapter>
diff --git a/doc/reference/modules/query_linq.xml b/doc/reference/modules/query_linq.xml
index 8a1c3849d7e..4ac6763dda3 100644
--- a/doc/reference/modules/query_linq.xml
+++ b/doc/reference/modules/query_linq.xml
@@ -425,7 +425,7 @@ using NHibernate.Linq;]]></programlisting>
 
     <para>
       Future results are supported by the Linq provider. They are not evaluated till one gets executed.
-      At that point, all defined future results are evaluated in one single round-trip to database.
+      At that point, all defined future results are evaluated in one single round-trip to the database.
     </para>
     <programlisting><![CDATA[// Define queries
 IFutureEnumerable<Cat> cats =
@@ -446,10 +446,7 @@ if (catCount.Value > 10)
 }
 ]]></programlisting>
     <para>
-      In above example, accessing <literal>catCount.Value</literal> does not trigger a round-trip to database:
-      it has been evaluated with <literal>cats.GetEnumerable()</literal> call. If instead
-      <literal>catCount.Value</literal> was accessed first, it would have executed both future and
-      <literal>cats.GetEnumerable()</literal> would have not trigger a round-trip to database.
+      See <xref linkend="performance-future" /> for more information.
     </para>
   </sect1>
 

From 9360e312d922c10f607126634e61b9c2c5938e61 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?=
 <12201973+fredericDelaporte@users.noreply.github.com>
Date: Sat, 7 Jul 2018 12:10:31 +0200
Subject: [PATCH 2/2] Fix grammar

---
 doc/reference/modules/performance.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/reference/modules/performance.xml b/doc/reference/modules/performance.xml
index 53578f36591..2a1aa29a721 100644
--- a/doc/reference/modules/performance.xml
+++ b/doc/reference/modules/performance.xml
@@ -1354,7 +1354,7 @@ ICollection<Policy> policies = CollectionHelper.ToArray<Policy>(results[1]);]]><
 
         <para>
             Future results are an alternative to using <xref linkend="performance-multi-query"/>.
-            They avoid the need to explicitly regroup queries, but they also hides which queries will
+            They avoid the need to explicitly regroup queries, but they also hide which queries will
             get executed: any pending future results of the session will be batched together, no
             matter where they were defined, included out-of-scope pending future results.
         </para>