Rework the broadcast API and document it (fixes #20740)

NEWS.md

@@ -290,6 +290,11 @@ This section lists changes that do not have deprecation warnings.
     Its return value has been removed. Use the `process_running` function
     to determine if a process has already exited.
 
+  * Broadcasting has been redesigned with an extensible public interface. The new API is
+    documented at https://docs.julialang.org/en/latest/manual/interfaces/#Interfaces-1.
+    `AbstractArray` types that specialized broadcasting using the old internal API will
+    need to switch to the new API. ([#20740])
+
 Library improvements
 --------------------
 
@@ -1490,6 +1495,7 @@ Command-line option changes
 [#20549]: https://github.com/JuliaLang/julia/issues/20549
 [#20575]: https://github.com/JuliaLang/julia/issues/20575
 [#20609]: https://github.com/JuliaLang/julia/issues/20609
+[#20740]: https://github.com/JuliaLang/julia/issues/20740
 [#20816]: https://github.com/JuliaLang/julia/issues/20816
 [#20889]: https://github.com/JuliaLang/julia/issues/20889
 [#20912]: https://github.com/JuliaLang/julia/issues/20912

base/cartesian.jl

@@ -41,7 +41,7 @@ end
 
 function _nloops(N::Int, itersym::Symbol, arraysym::Symbol, args::Expr...)
     @gensym d
-    _nloops(N, itersym, :($d->indices($arraysym, $d)), args...)
+    _nloops(N, itersym, :($d->Base.indices($arraysym, $d)), args...)
 end
 
 function _nloops(N::Int, itersym::Symbol, rangeexpr::Expr, args::Expr...)

base/deprecated.jl

@@ -2119,6 +2119,17 @@ end
 finalizer(f::Ptr{Void}, o::Ptr{Void}) = invoke(finalizer, Tuple{Ptr{Void}, Any}, f, o)
 finalizer(f::Ptr{Void}, o::Function) = invoke(finalizer, Tuple{Ptr{Void}, Any}, f, o)
 
+# Broadcast extension API (#23939)
+@eval Broadcast begin
+    Base.@deprecate_binding containertype combine_styles false
+    Base.@deprecate_binding _containertype BroadcastStyle false
+    Base.@deprecate_binding promote_containertype BroadcastStyle false
+    Base.@deprecate_binding broadcast_c! broadcast! false ", broadcast_c!(f, ::Type, ::Type, C, As...) should become broadcast!(f, C, As...) (see the manual chapter Interfaces)"
+    Base.@deprecate_binding broadcast_c broadcast false ", `broadcast_c(f, ::Type{C}, As...)` should become `broadcast(f, C, nothing, nothing, As...))` (see the manual chapter Interfaces)"
+    Base.@deprecate_binding broadcast_t broadcast false ", broadcast_t(f, ::Type{ElType}, shape, iter, As...)` should become `broadcast(f, Broadcast.DefaultArrayStyle{N}(), ElType, shape, As...))` (see the manual chapter Interfaces)"
+end
+
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/exports.jl

@@ -18,6 +18,7 @@ export
     Threads,
     Iterators,
     Distributed,
+    Broadcast,
 
 # Types
     AbstractChannel,

base/linalg/uniformscaling.jl

@@ -99,7 +99,7 @@ for (t1, t2) in ((:UnitUpperTriangular, :UpperTriangular),
             ($op)(UL::$t2, J::UniformScaling) = ($t2)(($op)(UL.data, J))
 
             function ($op)(UL::$t1, J::UniformScaling)
-                ULnew = copy_oftype(UL.data, Base.Broadcast._broadcast_eltype($op, UL, J))
+                ULnew = copy_oftype(UL.data, Broadcast.combine_eltypes($op, UL, J))
                 for i = 1:size(ULnew, 1)
                     ULnew[i,i] = ($op)(1, J.λ)
                 end
@@ -110,7 +110,7 @@ for (t1, t2) in ((:UnitUpperTriangular, :UpperTriangular),
 end
 
 function (-)(J::UniformScaling, UL::Union{UpperTriangular,UnitUpperTriangular})
-    ULnew = similar(parent(UL), Base.Broadcast._broadcast_eltype(-, J, UL))
+    ULnew = similar(parent(UL), Broadcast.combine_eltypes(-, J, UL))
     n = size(ULnew, 1)
     ULold = UL.data
     for j = 1:n
@@ -126,7 +126,7 @@ function (-)(J::UniformScaling, UL::Union{UpperTriangular,UnitUpperTriangular})
     return UpperTriangular(ULnew)
 end
 function (-)(J::UniformScaling, UL::Union{LowerTriangular,UnitLowerTriangular})
-    ULnew = similar(parent(UL), Base.Broadcast._broadcast_eltype(-, J, UL))
+    ULnew = similar(parent(UL), Broadcast.combine_eltypes(-, J, UL))
     n = size(ULnew, 1)
     ULold = UL.data
     for j = 1:n
@@ -144,7 +144,7 @@ end
 
 function (+)(A::AbstractMatrix, J::UniformScaling)
     n = checksquare(A)
-    B = similar(A, Base.Broadcast._broadcast_eltype(+, A, J))
+    B = similar(A, Broadcast.combine_eltypes(+, A, J))
     copy!(B,A)
     @inbounds for i = 1:n
         B[i,i] += J.λ
@@ -154,7 +154,7 @@ end
 
 function (-)(A::AbstractMatrix, J::UniformScaling)
     n = checksquare(A)
-    B = similar(A, Base.Broadcast._broadcast_eltype(-, A, J))
+    B = similar(A, Broadcast.combine_eltypes(-, A, J))
     copy!(B, A)
     @inbounds for i = 1:n
         B[i,i] -= J.λ
@@ -163,7 +163,7 @@ function (-)(A::AbstractMatrix, J::UniformScaling)
 end
 function (-)(J::UniformScaling, A::AbstractMatrix)
     n = checksquare(A)
-    B = convert(AbstractMatrix{Base.Broadcast._broadcast_eltype(-, J, A)}, -A)
+    B = convert(AbstractMatrix{Broadcast.combine_eltypes(-, J, A)}, -A)
     @inbounds for j = 1:n
         B[j,j] += J.λ
     end