Merge branch 'master' into ColumnAndFormula

Author: fredericDelaporte

Tools/packages.config

@@ -7,7 +7,7 @@
   <package id="NUnit.Extension.NUnitV2ResultWriter" version="3.6.0" targetFramework="net461" />
   <package id="NUnit.Extension.TeamCityEventListener" version="1.0.2" targetFramework="net461" />
   <package id="NUnit.Extension.VSProjectLoader" version="3.6.0" targetFramework="net461" />
-  <package id="CSharpAsyncGenerator.CommandLine" version="0.8.2.7" targetFramework="net461" />
+  <package id="CSharpAsyncGenerator.CommandLine" version="0.8.2.9" targetFramework="net461" />
   <package id="vswhere" version="2.1.4" targetFramework="net461" />
   <package id="gitreleasemanager" version="0.7.0" targetFramework="net461" />
 </packages>

doc/reference/modules/basic_mapping.xml

@@ -3982,12 +3982,11 @@
             </para>
 
             <para>
-                The <literal>ICompositeUserType</literal>, <literal>IEnhancedUserType</literal>,
-                <literal>INullableUserType</literal>, <literal>IUserCollectionType</literal>,
-                and <literal>IUserVersionType</literal> interfaces provide support for more specialized
-                uses.
+                The <literal>IEnhancedUserType</literal>, <literal>IUserVersionType</literal>,
+                and <literal>IUserCollectionType</literal> interfaces provide support for more specialized
+                uses. The later is to be used with collections, see <xref linkend="collections-persistent" />.
             </para>
-            
+
             <para>
                 You may even supply parameters to an <literal>IUserType</literal> in the mapping file. To
                 do this, your <literal>IUserType</literal> must implement the

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 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>
+
+        <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>

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>
 

src/AsyncGenerator.yml

@@ -98,6 +98,12 @@
     - conversion: Ignore
       name: QuoteTableAndColumns
       containingTypeName: SchemaMetadataUpdater
+    - conversion: Ignore
+      name: GetEnumerator
+      containingTypeName: DelayedEnumerator
+    - conversion: Ignore
+      name: GetEnumerator
+      containingTypeName: IFutureEnumerable
     - conversion: ToAsync
       name: ExecuteReader
       containingTypeName: IBatcher