diff --git a/src/Core/Core.jl b/src/Core/Core.jl index 55198526..213949d0 100644 --- a/src/Core/Core.jl +++ b/src/Core/Core.jl @@ -12,6 +12,7 @@ import DocStringExtensions: TYPEDEF, TYPEDSIGNATURES include("types.jl") include("tags.jl") +include("caches.jl") include("default.jl") # Private utilities @@ -24,7 +25,8 @@ include("palette.jl") include("display.jl") # Export public API -export ctNumber, matrix2vec, to_out_of_place, @ensure +export ctNumber, matrix2vec, to_out_of_place, make_coerce, @ensure +export AbstractTag, AbstractCache export Style, Palette export DEFAULT_PALETTE, MONOCHROME_PALETTE, HIGH_CONTRAST_PALETTE export current_palette, set_palette!, set_color!, reset_palette!, show_palette diff --git a/src/Core/caches.jl b/src/Core/caches.jl new file mode 100644 index 00000000..226611e7 --- /dev/null +++ b/src/Core/caches.jl @@ -0,0 +1,27 @@ +""" +$(TYPEDEF) + +Abstract base type for computation caches. + +Caches store pre-allocated buffers and prepared plans (for example automatic +differentiation plans) so that repeated computations avoid reallocating on every +call. Concrete cache types are defined by the packages or extensions that provide +a specific backend. + +# Interface Requirements + +Concrete cache subtypes typically: +- Hold pre-allocated buffers and/or a prepared plan +- Are constructed once and reused across many calls +- Are backend- or extension-specific + +# Example +```julia +struct MyCache <: AbstractCache + buffer::Vector{Float64} +end +``` + +See also: [`AbstractTag`](@ref). +""" +abstract type AbstractCache end diff --git a/src/Core/function_utils.jl b/src/Core/function_utils.jl index effdfe26..68988ffd 100644 --- a/src/Core/function_utils.jl +++ b/src/Core/function_utils.jl @@ -30,3 +30,38 @@ function to_out_of_place(f!, n; T=Float64) end return isnothing(f!) ? nothing : f end + +""" + make_coerce(x) -> coerce_fn + +Return a coercion function matching the shape of `x`. + +For scalars (`Number`), returns `only`, which extracts the single element from a +1-element vector. For arrays (`AbstractVector`, `AbstractMatrix`), returns +`identity` (a no-op). This is used to map a uniform vector-valued result back to +the natural shape of the original input. + +# Arguments +- `x`: A value whose type determines the coercion strategy. + +# Returns +- A coercion function with signature `(y) -> coerced_y`. + +# Example +```julia-repl +julia> coerce_scalar = make_coerce(1.0); + +julia> coerce_scalar([5.0]) +5.0 + +julia> coerce_vector = make_coerce([1.0, 2.0]); + +julia> coerce_vector([3.0, 4.0]) +2-element Vector{Float64}: + 3.0 + 4.0 +``` +""" +make_coerce(::Number) = only +make_coerce(::AbstractVector) = identity +make_coerce(::AbstractMatrix) = identity