Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ module's `.fsi` and the `.fs` on its `.fs`, so that Visual Studio shows them as
│ │ ├── ListArrays.fs – the List functions of two or three lists, over arrays
│ │ ├── Snapshot.fs – the snapshots in arrays of the collections without an underlying array
│ │ ├── Collectors.fs – the accumulators that build an indexed list from many collections
│ │ ├── Walk.fs – the loops over an indexed list with the enumerator that is faster for the element type
│ │ ├── Buffers.fs – the arrays, new or rented, in which the elements of a result wait for their tree
│ │ ├── Lengths.fs – the lengths of queues and stacks, counted as far as a caller needs
│ │ ├── DescendingSorts.fs – the stable descending sorts in the order of F# generic comparison
│ │ └── ListRanges.fs – the range checks of the functions that wrap members of ImmutableList
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@
<Compile Include="Helper\ListArrays.fs" />
<Compile Include="Helper\Snapshot.fs" />
<Compile Include="Helper\Collectors.fs" />
<Compile Include="Helper\Walk.fs" />
<Compile Include="Helper\Buffers.fs" />
<Compile Include="Helper\Lengths.fs" />
<Compile Include="Helper\DescendingSorts.fs" />
<Compile Include="Helper\ListRanges.fs" />
Expand Down
142 changes: 142 additions & 0 deletions src/FSharp.Collections.Immutable/Helper/Buffers.fs
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
/// <summary>
/// The buffer in which a function collects the elements that it chooses one by one, until it builds the tree of the result
/// (ADR 0001, D5).
/// </summary>
/// <remarks>
/// <para>
/// A result of unknown length waits in a <see cref="T:System.Collections.Generic.List`1"/> that doubles its array as it
/// fills, and the tree is built once, from its elements. The growth costs the copies, and for a result of some 20 000
/// integers or 10 000 references or more the arrays of the growth are allocated in the large object heap, which a collection
/// of the second generation reclaims; for a million elements the list allocated 18 % (integers) to 35 % (strings) more than
/// the tree needs.
/// </para>
/// <para>
/// The number of elements to choose from is known, and it bounds the result. The buffer takes an array of that length: a
/// new one for a short result, where the array is cheap and the pool would only add its own work, and one rented from
/// <see cref="P:System.Buffers.ArrayPool`1.Shared"/> for a long one, which allocates nothing in the steady state. An array
/// of the length of the source is more than the result needs when few of the elements are chosen, and it would be the
/// array of a hundred million elements for a list of that length. The rented array is therefore at most
/// <see cref="F:FSharp.Collections.Immutable.Buffers.PooledUpTo"/> elements long; a longer result moves into a list.
/// </para>
/// <para>
/// The buffer is disposable, and the function that uses it disposes it: the rented array goes back to the pool also when
/// the chooser throws before the list is built.
/// </para>
/// </remarks>
module internal FSharp.Collections.Immutable.Buffers

open System
open System.Buffers
open System.Collections.Generic
open System.Collections.Immutable
open System.Runtime.CompilerServices
open System.Runtime.InteropServices

/// <summary>
/// The least length of the source for which the buffer is rented from the pool.
/// </summary>
/// <remarks>
/// For 4 to 2048 elements, an array of its own and a rented one took the same time, 0 to 20 % less than the list when all
/// of the elements were chosen; the first call that rents an array of a length allocates it, and the first call took 6 to
/// 81 µs for 4 to 2048 elements.
/// An array below the limit is a small allocation that the next collection of the youngest generation reclaims.
/// </remarks>
[<Literal>]
let PooledFrom = 1024

/// <summary>
/// The most elements in the array that the buffer rents; a result that is longer moves into a list.
/// </summary>
[<Literal>]
let PooledUpTo = 1048576

/// <summary>
/// Collects the elements that a function chooses from a source of a known length, and builds the indexed list of them.
/// </summary>
/// <typeparam name="T">The type of the elements.</typeparam>
/// <param name="bound">The number of elements to choose from, which is the most that the result can have.</param>
/// <param name="pool">The pool that lends the array of a long result.</param>
/// <remarks>
/// A buffer is used once: <see cref="M:FSharp.Collections.Immutable.Buffers.ChosenBuffer`1.ToImmutable"/> ends it. The
/// pool is a parameter so that a test can give one that records what it lends and what it gets back.
/// </remarks>
[<Sealed>]
type ChosenBuffer<'T> (bound : int, pool : ArrayPool<'T>) =

let pooled = bound >= PooledFrom

let mutable buffer : 'T array =
if bound = 0 then Array.Empty<'T>()
elif pooled then pool.Rent (min bound PooledUpTo)
else Array.zeroCreate bound

let mutable count = 0
let mutable overflow : ResizeArray<'T> | null = null

/// <summary>
/// Creates a buffer that rents the array of a long result from <see cref="P:System.Buffers.ArrayPool`1.Shared"/>.
/// </summary>
/// <param name="bound">The number of elements to choose from, which is the most that the result can have.</param>
new (bound : int) = new ChosenBuffer<'T> (bound, ArrayPool<'T>.Shared)

/// Returns the rented array to the pool, cleared as far as it was written when it holds references. The buffer is
/// left with an empty array, which is full at once, so that an element goes to the slow path of Add.
member private _.Release () =
if pooled && buffer.Length > 0 then
if RuntimeHelpers.IsReferenceOrContainsReferences<'T>() then
Array.Clear (buffer, 0, count)

pool.Return (buffer, false)

buffer <- Array.Empty<'T>()
count <- 0

/// Moves the elements of the full array into a list that grows, and gives the array back.
member private this.Spill () : ResizeArray<'T> =
let spilled = ResizeArray<'T>(buffer.Length * 2)
CollectionsMarshal.SetCount (spilled, count)
ReadOnlySpan<'T>(buffer, 0, count).CopyTo(CollectionsMarshal.AsSpan spilled)
this.Release ()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we add a test covering the spill path with a reference type?
It would be useful to assert that the rented array is cleared before being returned to the pool.

overflow <- spilled
spilled

[<MethodImpl(MethodImplOptions.NoInlining)>]
member private this.AddSlow (value : 'T) =
match overflow with
| null -> this.Spill().Add value
| spilled -> spilled.Add value

/// <summary>
/// Appends an element.
/// </summary>
/// <param name="value">The element.</param>
[<MethodImpl(MethodImplOptions.AggressiveInlining)>]
member this.Add (value : 'T) =
if count = buffer.Length then
this.AddSlow value
else
buffer[count] <- value
count <- count + 1

/// <summary>
/// The indexed list of the elements that were added, in their order.
/// </summary>
/// <returns>The indexed list, which is empty when nothing was added.</returns>
member this.ToImmutable () : ImmutableList<'T> =
match overflow with
| null ->
let result = ImmutableList.Create<'T>(ReadOnlySpan<'T>(buffer, 0, count))
this.Release ()
result
| spilled -> ImmutableList.Create<'T>(Span<'T>.op_Implicit(CollectionsMarshal.AsSpan spilled))

interface IDisposable with

/// <summary>
/// Returns the rented array to the pool when the buffer still holds it.
/// </summary>
/// <remarks>
/// A buffer that built its list, or that moved its elements into a list, holds no rented array, and nothing
/// happens. The call matters when the chooser throws before the list is built.
/// </remarks>
member this.Dispose () = this.Release ()
46 changes: 46 additions & 0 deletions src/FSharp.Collections.Immutable/Helper/Snapshot.fs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
/// </remarks>
module internal FSharp.Collections.Immutable.Snapshot

open System
open System.Linq

/// <summary>
Expand Down Expand Up @@ -42,3 +43,48 @@ open System.Linq
let ofSeq (name : string) (source : seq<'T>) : 'T array =
checkNotNull name source
Enumerable.ToArray source

/// <summary>
/// A sequence in a form from which the BCL builds the tree of an
/// <see cref="T:System.Collections.Immutable.ImmutableList`1"/> in one pass: the elements of an F# list in a new array,
/// and any other sequence as it is.
/// </summary>
/// <param name="source">The sequence, which the caller has checked for <see langword="null"/>.</param>
/// <returns>A new array of the elements of an F# list, or <paramref name="source"/> itself.</returns>
/// <remarks>
/// <para>
/// <see cref="M:System.Collections.Immutable.ImmutableList.CreateRange``1(System.Collections.Generic.IEnumerable{``0})"/>,
/// <see cref="M:System.Collections.Immutable.ImmutableList`1.AddRange(System.Collections.Generic.IEnumerable{`0})"/> and
/// <see cref="M:System.Collections.Immutable.ImmutableList`1.InsertRange(System.Int32,System.Collections.Generic.IEnumerable{`0})"/>,
/// and the same members of the builder, build a tree by indexing a sequence that implements
/// <see cref="T:System.Collections.Generic.IReadOnlyList`1"/>. An F# list implements it, and its indexer walks the list
/// from its head, so the build takes time that grows with the square of the length: 67 ms, 257 ms and 1.16 s for an
/// insertion of 10 000, 20 000 and 40 000 elements. The copy of the list in an array is one pass, and so is the build
/// from the array: 0.16 ms, 0.37 ms and 0.68 ms for the same insertions.
/// </para>
/// <para>
/// The interface is covariant, so the BCL also indexes a list of strings that is given as a sequence of objects. Such a
/// value is not a <see cref="T:Microsoft.FSharp.Collections.FSharpList`1"/> of <see cref="T:System.Object"/>: the type
/// test for a list of the element type, which is the cheap one and comes first, does not find it, and the type of the
/// value tells that it is a list.
/// </para>
/// <para>
/// Reading the type of the value takes some 300 processor cycles, a sixth of the insertion of ten elements into a list
/// of a hundred. An array, a <see cref="T:System.Collections.Generic.List`1"/> and the immutable collections implement
/// <see cref="T:System.Collections.ICollection"/>, which an F# list does not, so one more type test returns them at once.
/// </para>
/// </remarks>
let forTree (source : seq<'T>) : seq<'T> =
match source with
| :? ('T list) as list -> List.toArray list
| :? System.Collections.ICollection -> source
| _ ->
let sourceType = source.GetType ()

if
sourceType.IsGenericType
&& Type.(=) (sourceType.GetGenericTypeDefinition (), typedefof<_ list>)
then
Enumerable.ToArray source
else
source
100 changes: 100 additions & 0 deletions src/FSharp.Collections.Immutable/Helper/Walk.fs
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
/// <summary>
/// The loops over the elements of an <see cref="T:System.Collections.Immutable.ImmutableList`1"/>, which walk it with the
/// enumerator that is the faster one for the type of the elements (ADR 0001, D5).
/// </summary>
/// <remarks>
/// <para>
/// <c>ImmutableList&lt;T&gt;.GetEnumerator</c> returns a struct. For a value type that is the fastest way to walk the list: the
/// compiler knows the struct, and its calls are direct and inlined. For a reference type the code of a generic function is
/// shared by all reference types, and each call of a member of a generic struct in it needs a lookup of the exact type
/// at run time. Walking the list through <see cref="T:System.Collections.Generic.IEnumerable`1"/> instead, with a boxed
/// enumerator and calls through the interface, took 0.56 to 0.70 times as long for strings (6 against 10 ns for an
/// element) and 1.1 to 1.5 times as long for integers. As functions of the library, iter and fold took 0.6 to 0.7 times
/// as long for strings of 100 to 100 000 elements, tryPick 0.6, mapi and scan 0.7 to 0.9, and none of them changed for
/// integers. The loop of mapFold stays as it was, because the same loop took 1.1 to 1.4 times as long there.
/// </para>
/// <para>
/// The test <c>typeof&lt;'T&gt;.IsValueType</c> is a constant for the compiler of the run time, so each instantiation of a
/// function keeps one of the two loops. The functions are inline, and the body of a loop is passed as a lambda that the
/// compiler inlines into both loops, so that a body is written once. A body cannot capture a mutable local, which is why
/// <see cref="M:FSharp.Collections.Immutable.Walk.iteri``1"/> and
/// <see cref="M:FSharp.Collections.Immutable.Walk.fold``2"/> count and carry the state themselves.
/// </para>
/// </remarks>
module internal FSharp.Collections.Immutable.Walk

open System.Collections.Immutable

/// <summary>
/// Calls an action for each element of a list, in order.
/// </summary>
/// <param name="action">The action.</param>
/// <param name="list">The list, which is not <see langword="null"/>.</param>
let inline iter ([<InlineIfLambda>] action : 'T -> unit) (list : ImmutableList<'T>) =
if typeof<'T>.IsValueType then
for item in list do
action item
else
for item in (list :> seq<'T>) do
action item

/// <summary>
/// Calls an action for each element of a list, in order, with the index of the element.
/// </summary>
/// <param name="action">The action.</param>
/// <param name="list">The list, which is not <see langword="null"/>.</param>
let inline iteri ([<InlineIfLambda>] action : int -> 'T -> unit) (list : ImmutableList<'T>) =
let mutable index = 0

if typeof<'T>.IsValueType then
for item in list do
action index item
index <- index + 1
else
for item in (list :> seq<'T>) do
action index item
index <- index + 1

/// <summary>
/// Threads a state through the elements of a list, in order.
/// </summary>
/// <param name="folder">The function that returns the next state for the state and the element.</param>
/// <param name="state">The first state.</param>
/// <param name="list">The list, which is not <see langword="null"/>.</param>
/// <returns>The last state.</returns>
let inline fold ([<InlineIfLambda>] folder : 'State -> 'T -> 'State) (state : 'State) (list : ImmutableList<'T>) =
let mutable state = state

if typeof<'T>.IsValueType then
for item in list do
state <- folder state item
else
for item in (list :> seq<'T>) do
state <- folder state item

state

/// <summary>
/// The first value that a chooser returns for the elements of a list, in order, without a call for the elements after it.
/// </summary>
/// <param name="chooser">The chooser.</param>
/// <param name="list">The list, which is not <see langword="null"/>.</param>
/// <returns>The first value, or <see langword="ValueNone"/>.</returns>
let inline tryPick ([<InlineIfLambda>] chooser : 'T -> 'U voption) (list : ImmutableList<'T>) =
let mutable result = ValueNone

if typeof<'T>.IsValueType then
let mutable enumerator = list.GetEnumerator ()

try
while result.IsNone && enumerator.MoveNext () do
result <- chooser enumerator.Current
finally
enumerator.Dispose ()
else
use enumerator = (list :> seq<'T>).GetEnumerator()

while result.IsNone && enumerator.MoveNext () do
result <- chooser enumerator.Current

result
11 changes: 5 additions & 6 deletions src/FSharp.Collections.Immutable/IndexedList/IIndexedList.fs
Original file line number Diff line number Diff line change
Expand Up @@ -370,17 +370,15 @@ let append (list1 : IIndexedList<'T>) (list2 : IIndexedList<'T>) =
[<CompiledName "Choose">]
let choose (chooser : 'T -> 'U voption) (list : IIndexedList<'T>) =
checkNotNull (nameof list) list
// The number of chosen elements is not known in advance, so they wait in a ResizeArray and CreateRange builds the
// balanced tree once. A builder rebalances its tree after every Add and took 2.3 times as long for 100 000
// elements; there is no tree of an input to join to its tree here, as collect and concat have (see Collectors).
let chosen = ResizeArray<'U>()
// As IndexedList.choose: the chosen elements wait in an array as long as the list (see Buffers)
use chosen = new Buffers.ChosenBuffer<'U> (list.Count)

for item in list do
match chooser item with
| ValueSome value -> chosen.Add value
| ValueNone -> ()

ImmutableList.CreateRange chosen
chosen.ToImmutable ()

[<CompiledName "ChunkBySize">]
let chunkBySize chunkSize (list : IIndexedList<'T>) =
Expand Down Expand Up @@ -446,7 +444,8 @@ let insertManyAt index (values : seq<'T>) (source : IIndexedList<'T>) =
// List checks the index before it reads the values
ListChecks.insertAt (nameof index) index source.Count
checkNotNullOrDefaultSeq (nameof values) values
source.InsertRange (index, values)
// InsertRange of an indexed list builds the tree of the values by indexing, as in IndexedList.insertManyAt
source.InsertRange (index, Snapshot.forTree values)

[<CompiledName "Map">]
let map (mapping : 'T -> 'U) (list : IIndexedList<'T>) =
Expand Down
Loading