juliadynamics / mixedstructtypes.jl

Easy-to-use sum types in Julia

DynamicSumTypes.jl

This package allows to combine multiple heterogeneous types in a single one. This helps to write type-stable code by avoiding Union-splitting, which has big performance drawbacks when many types are unionized.

Another aim of this library is to provide a syntax as similar as possible to standard Julia structs to facilitate its integration within other libraries.

The @sum_structs macro implements two strategies to create a compact representation of the types: the default one merges all fields of each struct in a unique type which is faster in many cases, while the second uses SumTypes.jl under the hood, which is more memory efficient and allows to mix mutable and immutable structs.

Even if there is only a unique type defined by this macro, you can access a symbol containing the conceptual type of an instance with the function kindof and use the @pattern macro to define functions which can operate differently on each kind.

Construct mixed structs

julia> using DynamicSumTypes

julia> abstract type AbstractA{X} end

julia>  # default version is :opt_speed
        @sum_structs A{X} <: AbstractA{X} begin
           @kwdef mutable struct B{X}
               a::X = 1
               b::Float64 = 1.0
           end
           @kwdef mutable struct C{X}
               a::X = 2
               c::Bool = true
           end
           @kwdef mutable struct D{X}
               a::X = 3
               const d::Symbol = :s
           end
           @kwdef mutable struct E{X}
               a::X = 4
           end
       end

julia> b = B(1, 1.5)
B{Int64}(1, 1.5)::A

julia> b.a
1

julia> b.a = 3
3

julia> kindof(b)
:B

julia> abstract type AbstractF{X} end

julia> @sum_structs :opt_memory F{X} <: AbstractF{X} begin
           @kwdef mutable struct G{X}
               a::X = 1
               b::Float64 = 1.0
           end
           @kwdef mutable struct H{X}
               a::X = 2
               c::Bool = true
           end
           @kwdef mutable struct I{X}
               a::X = 3
               const d::Symbol = :s
           end
           @kwdef mutable struct L{X}
               a::X = 4
           end
       end

julia> g = G(1, 1.5)
G{Int64}(1, 1.5)::F

julia> g.a
1

julia> g.a = 3
3

julia> kindof(g)
:G

Define functions on the mixed structs

There are currently two ways to define function on the types created with this package:

• Use manual branching;
• Use the @pattern macro.

For example, let's say we want to create a sum function where different values are added depending on the kind of each element in a vector:

julia> function sum1(v) # with manual branching
           s = 0
           for x in v
               if kindof(x) === :B
                   s += value_B(1)
               elseif kindof(x) === :C
                   s += value_C(1)
               elseif kindof(x) === :D
                   s += value_D(1)
               elseif kindof(x) === :E
                   s += value_E(1)
               else
                   error()
               end
           end
           return s
       end
sum1 (generic function with 1 method)

julia> value_B(k::Int) = k + 1;

julia> value_C(k::Int) = k + 2;

julia> value_D(k::Int) = k + 3;

julia> value_E(k::Int) = k + 4;

julia> function sum2(v) # with @pattern macro
           s = 0
           for x in v
               s += value(1, x)
           end
           return s
       end
sum2 (generic function with 1 method)

julia> @pattern value(k::Int, ::B) = k + 1;

julia> @pattern value(k::Int, ::C) = k + 2;

julia> @pattern value(k::Int, ::D) = k + 3;

julia> @pattern value(k::Int, ::E) = k + 4;

julia> v = A{Int}[rand((B,C,D,E))() for _ in 1:10^6];

julia> sum1(v)
2499517

julia> sum2(v)
2499517

As you can see the version using the @pattern macro is much less verbose and more intuitive. In some more advanced cases the verbosity of the first approach could be even stronger.

Since the macro essentially reconstruct the branching version described above, to ensure that everything will work correctly when using it, do not define functions operating on the main type of a mixed struct without using the @pattern macro.

Consult the API page for more information on the available functionalities.

Benchmark against a Union of types

Let's see briefly how the two macros compare performance-wise in respect to a Union of types:

julia> @kwdef mutable struct M{X}
           a::X = 1
           b::Float64 = 1.0
       end

julia> @kwdef mutable struct N{X}
           a::X = 2
           c::Bool = true
       end

julia> @kwdef mutable struct O{X}
           a::X = 3
           const d::Symbol = :s
       end

julia> @kwdef mutable struct P{X}
           a::X = 4
       end

julia> vec_union = Union{M{Int},N{Int},O{Int},P{Int}}[rand((M,N,O,P))() for _ in 1:10^6];

julia> vec_sum_memory = F{Int}[rand((G,H,I,L))() for _ in 1:10^6];

julia> vec_sum_speed = A{Int}[rand((B,C,D,E))() for _ in 1:10^6];

julia> Base.summarysize(vec_union)
22003112

julia> Base.summarysize(vec_sum_memory)
30004176

julia> Base.summarysize(vec_sum_speed)
48000040

julia> using BenchmarkTools

julia> @btime sum(x.a for x in $vec_union);
  26.886 ms (999805 allocations: 15.26 MiB)

julia> @btime sum(x.a for x in $vec_sum_memory);
  6.585 ms (0 allocations: 0 bytes)

julia> @btime sum(x.a for x in $vec_sum_speed);
  1.747 ms (0 allocations: 0 bytes)

In this case, @sum_structs :opt_speed types are almost 15 times faster than Union ones, even if they require more than double the memory. Whereas, as expected, @sum_structs :opt_memory types are less time efficient, but the memory increase in respect to Union types is smaller.

Contributing

Contributions are welcome! If you encounter any issues, have suggestions for improvements, or would like to add new features, feel free to open an issue or submit a pull request.

mixedstructtypes.jl's Issues

Rework automatic conversion without type-piracy

Unfortunately last pr #20 is not good enough

This can be done with an adaptation of the technique discussed in https://discourse.julialang.org/t/how-not-to-commit-type-piracy-when-handling-automatic-conversion-for-field-with-union-type/109877/5, thanks to @abraemer for the help

TagBot trigger issue

This issue is used to trigger TagBot; feel free to unsubscribe.

If you haven't already, you should update your TagBot.yml to include issue comment triggers.
Please see this post on Discourse for instructions and more details.

If you'd like for me to do this for you, comment TagBot fix on this issue.
I'll open a PR within a few hours, please be patient!

Support a dispatch macro to avoid the need of branching

E.g. say we have

using MixedStructTypes

abstract type AbstractShape end

@sum_structs Shape <: AbstractShape begin
    @kwdef struct Square
        side::Float64 = rand()
    end   
    @kwdef struct Rectangle
        width::Float64 = rand()
        height::Float64 = rand()
    end
    @kwdef struct Triangle
        base::Float64 = rand()
        height::Float64 = rand()
    end
    @kwdef struct Circle
        radius::Float64 = rand()
    end
end

currently we can define an area function like so:

function area(sh)
    if kindof(sh) === :Square
        area_square(sh)
    elseif kindof(sh) === :Rectangle
        area_rectangle(sh)
    elseif kindof(sh) === :Triangle
        area_triangle(sh)
    elseif kindof(sh) === :Circle
        area_circle(sh)
    else
        area_default(sh)
    end
end
   
area_square(s) = s.side * s.side
area_rectangle(r) = r.width * r.height
area_triangle(t) = 1.0/2.0 * t.base * t.height
area_circle(c) = π * c.radius^2
area_default(::AbstractShape) = 0.0

but actually we can generate all of this. So probably something like this should suffice

@dispatch area(s::Square) = s.side * s.side
@dispatch area(r::Rectangle) = r.width * r.height
@dispatch area(t::Triangle) = 1.0/2.0 * t.base * t.height
@dispatch area(c::Circle) = π * c.radius^2
@dispatch area(::AbstractShape) = 0.0

dispatch macro still doesn't support dispatching on the overall type

e.g. in the example in the readme, let's say only B has a special value

@dispatch value(::B) = 2

then it would be useful if this would also work to reduce verbosity:

@dispatch value(::A) = 1

which would mean that all other kinds have that value

Base.copy(instance) with the struct_sum_type macro fails on 1.8

Strangely it fails only on 1.8 with the struct_sum_type macro, it seems a convert problem in SumTypes.jl

CI run: https://github.com/JuliaDynamics/MixedStructTypes.jl/actions/runs/7647801175/job/20839415780