New package: Collects.jl - meant to improve upon and generalize the interface of collect

Package Announcements
, , , ,
1

Just requested the registration of the new package, Collects.jl, meaning it should be registered after three days pass.

Basically it’s meant to replace collect, especially when the desired output container type is not Array, as the new package’s interface takes the container type as a method argument. Another generalization with respect to collect is that the user now has control over how empty iterators are handled. In particular, type inference is not used by default, which is friendlier to the compiler optimizer, and to the correctness of the package ecosystem. The default behavior is to throw when the element type can’t be deduced from either eltype, the elements of the iterator, or the output type argument.

The main exported names are Collect and collect_as. The former is meant for package authors implementing the Collects.jl interface, while the latter should be more convenient for users.

The collect_as function behaves similarly to collect, except that the first argument is the container type instead of the element type. Apart from two positional arguments, collect_as also takes an optional keyword argument, controlling how the element type of empty iterators is handled. See the Readme for more information:

Some notes:

  • Collects.jl implements its interface for (some) collection types from Base, otherwise it’s an interface package, meaning that its interface is meant to be implemented in other packages for types that package owns.

  • Unlike collect, Collects.jl does not use Base.IteratorEltype. Example where Base.IteratorEltype matters for collect:

    julia> i = Any[3, 3.0];

julia> o = Iterators.map(identity, i);

julia> eltype(collect(i))
Any

julia> eltype(collect(o))
Real

    Collects.jl basically assumes Base.IteratorEltype(iterator) === Base.EltypeUnknown(). My rationale for this choice is that someone who wants Base.HasEltype() can easily do collect_as(Vector{eltype(iter)}, iter):

    julia> eltype(collect_as(Vector, i))
Real

julia> eltype(collect_as(Vector, o))
Real

julia> eltype(collect_as(Vector{eltype(i)}, i))
Any

julia> eltype(collect_as(Vector{eltype(o)}, o))
Any
37 Likes
Memory Comprehensions
[ANN] FixedSizeArrays.jl: What Array probably should have been
How to implement promotion for functions like `collect` and `map`?
2

I know this is going to be against the stream of “everything should be externalized”, but it feels like a good function to be in located in Base. I’m quite sure I would use this function if it was in Base, but am equally sure that I will not add Collects.jl as a requirement to any of my packages. There is just too much overhead for a single and simple function.

4 Likes
3

Sorry for the last minute bikeshedding, but I think fromiter would be a good name for this. It reads a little more naturally with the argument order, i.e. fromiter(Set, x) is like

Set `fromiter` x

which is similar to how contains(haystack, needle) can be read as

haystack `contains` needle

and occursin(needle, haystack) can be read as

needle `occursin` haystack

There is also some precedence for fromiter or from_iter in other languages, e.g.,

1 Like
4

Opening a poll for voting on alternative names, but I’m not willing to give up collect in the name, unless there’s a really good alternative. EDIT: uhh the package just got registered. I’ll make a v2 ASAP if necessary.

Sure, but there’s even more precedent for collect, I think.

Poll

What should the name of the user-facing function be?
  • collect_as
  • collectas
  • collect_to
  • collectto
  • collect_into
  • collectinto
  • collect_from
  • collectfrom
0 voters
5

collect already is in Base, though. If a PR is going to be made against JuliaLang/julia to add a replacement for collect, the replacement better be really good, otherwise there’s going to be yet another replacament added to Base two years later. And the only way to be sure is to test it out in the package ecosystem.

I’m sure you’re underestimating the choices that went into both the design of the interface and into the implementation.

Case in point, even though collect_as existed for some time as a function in FixedSizeArrays.jl, after creating this standalone package, and even after starting the registration process, there’s been significant changes.

Furthermore, what you’re saying doesn’t really make sense: this is an interface package, meant to have its interface implemented by an arbitrary number of other packages. So you can’t just reimplement it or vendor it locally.

3 Likes
6

Regarding the poll, is there someone able to see the results? I just get this meaningless attempt at a visualization:

poll
poll513×430 14.9 KB

The poll should be configured so that each vote is public, but I don’t understand if that is actually available.

7

Seems like the ranked choice voting is supposed to go in rounds and in the end have quite different visuals: the third image in this original PR and a bunch of images in this thread show it. Not sure why this one displays the results in this useless way. Perhaps worth creating a thread in that meta.discourse website after getting info about the Discourse version being used here from the admins/mods.

1 Like
8

V1.1 is released as of recently, coming with a new feature, requested by @PatrickHaecker: collect_as(output_type) now returns something akin to Base.Fix1(collect_as, output_type) instead of throwing MethodError.

There has also been lots of performance and inference improvements. Some day maybe I create a nice benchmark suite with lots of different classes of iterators, comparing collect_as against collect.

Also planning on expanding the interface with the ability for the caller to specify a size hint. This might be helpful for the iterator types which do not support length, in case the caller has an idea for the minimum length. On the issue tracker: allow caller to provide size hint · Issue #55 · JuliaCollections/Collects.jl · GitHub

Also, there is now a docs page, via Github Pages and Documenter.jl.

4 Likes
9

Thanks, @nsajko, for this addition. Although Arrays are great, Julia has so many more great collections and Collects.jl makes it even easier to use and mix them.

1 Like
10

OK, so here is some measurements.

Here are the different configurations varied in the experiment:

  • collect vs collect_as

  • With element type specified (collect(elt, iterator) or collect_as(Array{elt}, iterator)) vs not specified (collect(iterator) or collect_as(Array, iterator)).

  • eltype(iterator) === Any vs eltype(iterator) === Float32.

  • Base.IteratorSize(iterator) === Base.HasLength() vs Base.IteratorSize(iterator) === Base.SizeUnknown()

  • With iterator length ranging from 1 to 600.

In total: 2^4 \cdot 600 benchmarks.

In all cases a call of iterate is cheap and elements of the iterator are Float32 numbers ranging from 1 to the length.

Relevant software versions:

  • Collects.jl v1.1.0

  • BenchmarkTools.jl v1.6.3

  • Julia 1.14.0-DEV.1734 (commit 4acab830b60)

Here’s a first attempt at a visualization:

vega-lite-defaulttheme
vega-lite-defaulttheme2403×737 463 KB

So it seems like performance is mostly the same between collect and collect_as, except in the case of iterators which have an imprecise eltype and, simultaneously, do not implement length (Base.SizeUnknown()). Even in the latter case there is no clear winner.

This is the Julia code for the benchmarks:

bench.jl 
module IteratorExample
    export iterator_example
    function identity_function(x)  # behaves the same as `identity`, but a new function, to avoid special code paths meant for `typeof(identity)`
        x
    end
    function returns_true_function(::Any)  # behaves the same as `Returns(true)`, but a new function, to avoid special code paths meant for `Returns`
        true
    end
    const iterator_with_obscured_eltype = Base.Fix1(Iterators.map, identity_function)
    const iterator_with_obscured_iteratorsize = Base.Fix1(Iterators.filter, returns_true_function)
    function iterator_with_length_start_step(; length, start, step)
        it = Iterators.countfrom(start, step)
        Iterators.take(it, length)
    end
    function branch((f, g), x, b::Bool)
        if b
            f(x)
        else
            g(x)
        end
    end
    function iterator_example(; length, start, step = true, precise_eltype::Bool, precise_iteratorsize::Bool)
        it = iterator_with_length_start_step(; length, start, step)
        it = branch((identity, iterator_with_obscured_eltype), it, precise_eltype)
        it = branch((identity, iterator_with_obscured_iteratorsize), it, precise_iteratorsize)
        it
    end
end

const samples = parse(Int, ARGS[1])
const evals = parse(Int, ARGS[2])
const min_n = parse(Int, ARGS[3])
const max_n = parse(Int, ARGS[4])

print(
    stderr,
    "samples = $samples\n",
    "evals = $evals\n",
    "min_n = $min_n\n",
    "max_n = $max_n\n",
)

using .IteratorExample
using Collects: collect_as
using BenchmarkTools: @benchmarkable

const IteratorId = Tuple{
    Bool,  # `eltype` is precise
    Bool,  # `IteratorSize` is precise
    Int,   # `length`
}

function iterator_ids(lengths)
    bools = (false, true)
    Iterators.product(bools, bools, lengths)
end

function measure_performance(
    (name, func)::Tuple{String, Any},
    (precise_eltype, precise_iteratorsize, iterator_length)::IteratorId,
)
    iterator = iterator_example(;
        length = iterator_length,
        start = 1f0,
        precise_eltype,
        precise_iteratorsize,
    )
    GC.gc()
    GC.gc()
    GC.enable(false)
    bench = @benchmarkable ($func)($iterator) evals=evals samples=samples seconds=Inf gctrial=false
    trial = run(bench)
    GC.enable(true)
    GC.gc()
    GC.gc()
    estimate = minimum(trial)
    iterator_id = (
        precise_eltype,
        precise_iteratorsize,
        iterator_length,
    )
    measurement = (;
        minimum_time = estimate.time,
        allocated_byte_count = estimate.memory,
        allocation_count = estimate.allocs,
    )
    (name, iterator_id, measurement)
end

function show_results_as_json_table_row(
    io::IO,
    name::String,
    (prec_e, prec_i, n)::IteratorId,
    (; minimum_time, allocated_byte_count, allocation_count),
)
    pr = Base.Fix1(print, io)
    f = Base.Fix1(pr, ", ")
    eltype_iterator = if prec_e
        "Float32"
    else
        "Any"
    end
    IteratorSize_iterator = if prec_i
        "HasLength()"
    else
        "SizeUnknown()"
    end
    pr("    { ")
    pr(lazy"\"BenchmarkTools.jl parameter `evals`\": $evals")
    f()
    pr(lazy"\"BenchmarkTools.jl parameter `samples`\": $samples")
    f()
    pr(lazy"\"description\": \"$name\"")
    f()
    pr(lazy"\"length(iterator)\": $n")
    f()
    pr(lazy"\"eltype(iterator)\": \"$eltype_iterator\"")
    f()
    pr(lazy"\"IteratorSize(iterator)\": \"$IteratorSize_iterator\"")
    f()
    pr(lazy"\"minimal measured time (ns)\": $minimum_time")
    f()
    pr(lazy"\"measured allocated bytes\": $allocated_byte_count")
    f()
    pr(lazy"\"measured allocations\": $allocation_count")
    pr(' ')
    pr("} ")
    nothing
end

function todo_how_to_name_this_function(f::F, arg) where {F}
    f()
    arg
end

function measure_and_report_as_json(io::IO)
    pr = Base.Fix1(print, io)
    f = splat(Base.Fix1(show_results_as_json_table_row, io)) ∘ measure_performance
    g = Base.Fix1(todo_how_to_name_this_function, Base.Fix1(pr, ",\n"))
    collects = (
        ("collect(x)", collect),
        ("collect(Float32, x)", (x -> collect(Float32, x))),
        ("collect_as(Array, x)", collect_as(Array)),
        ("collect_as(Array{Float32}, x)", collect_as(Array{Float32})),
    )
    it = Iterators.product(collects, iterator_ids(min_n:max_n))
    (fir, res) = Iterators.peel(it)
    pr("[\n")
    f(fir...)
    foreach(splat(f) ∘ g, res)
    pr("\n]\n")
end

measure_and_report_as_json(stdout)

Linked is the Vega Lite JSON, including the data inline:

EDIT: here is a visualization for iterator lengths not greater than 50:

50
502382×736 195 KB

3 Likes