Rename iswriteable (#102)

* rename iswriteable to maywrite

* add deprecation

* v0.2.8

Author: mcabbott

Project.toml

@@ -1,7 +1,7 @@
 name = "Optimisers"
 uuid = "3bd65402-5787-11e9-1adc-39752487f4e2"
 authors = ["Mike J Innes <mike.j.innes@gmail.com>"]
-version = "0.2.7"
+version = "0.2.8"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

src/Optimisers.jl

@@ -24,7 +24,7 @@ which will be subtracted from the parameters, and the updated state (if any) for
 the next iteration, as a tuple `(state, gradient)`.
 
 For efficiency it is free to mutate the old state, but only what is returned will be used.
-Ideally this should check `iswriteable(x)`, which the built-in rules do via [`@..`](@ref).
+Ideally this should check `maywrite(x)`, which the built-in rules do via [`@..`](@ref).
 
 The initial state is `init(rule::RuleType, parameters)`.
 

src/interface.jl

@@ -24,7 +24,7 @@ function setup(rule, x; seen = Base.IdSet())
   end
 end
 
-subtract!(x, x̄) = iswriteable(x) ? (x .= x .- x̄) : eltype(x).(x .- x̄)
+subtract!(x, x̄) = maywrite(x) ? (x .= x .- x̄) : eltype(x).(x .- x̄)
 
 update!(::Nothing, x, ::Zero, ::Zero...) = nothing, x
 update!(::Nothing, x, x̄s...) = nothing, x
@@ -44,8 +44,8 @@ function update!(tree, x, x̄s...)
 end
 
 function update(tree, x, x̄s...)
-  t′ = fmap(copy, tree; exclude = iswriteable)
-  x′ = fmap(copy, x; exclude = iswriteable)
+  t′ = fmap(copy, tree; exclude = maywrite)
+  x′ = fmap(copy, x; exclude = maywrite)
   update!(t′, x′, x̄s...)
 end
 
@@ -56,8 +56,17 @@ isnumeric(x::AbstractArray{<:Number}) = isleaf(x)  # isleaf to allow for e.g. tr
 isnumeric(x::AbstractArray{<:Integer}) = false
 isnumeric(x) = false
 
-iswriteable(::DenseArray) = true  # more elaborate versions are possible, wait until needed?
-iswriteable(_) = false
+"""
+    maywrite(x) -> Bool
+
+Should return `true` if we are completely sure that `update!` can write new
+values into `x`. Otherwise `false`, indicating a non-mutating path.
+For now, simply `x isa DenseArray` allowing `Array`, `CuArray`, etc. 
+"""
+maywrite(::DenseArray) = true  # see https://github.com/FluxML/Optimisers.jl/issues/99 for discussion
+maywrite(_) = false
+
+@deprecate iswriteable maywrite false  # remove when releasing Optimisers@0.3
 
 """
     trainable(x::Layer) -> NamedTuple
@@ -84,13 +93,13 @@ end
     @.. x = x + y
 
 Sometimes in-place broadcasting macro, for use in `apply!` rules.
-If `iswriteable(x)` then it is just `@. x = rhs`, but if not, it becomes `x = @. rhs`.
+If `maywrite(x)` then it is just `@. x = rhs`, but if not, it becomes `x = @. rhs`.
 """
 macro var".."(ex)
   Meta.isexpr(ex, :(=)) || throw("the macro @.. only accepts assignment, like @.. x = y + z")
   dst = esc(ex.args[1])
   src = esc(Broadcast.__dot__(ex.args[2]))
-  :($dst = if $iswriteable($dst)
+  :($dst = if $maywrite($dst)
       $dst .= $src
     else
       $src

test/runtests.jl

@@ -25,7 +25,7 @@ Optimisers.trainable(x::TwoThirds) = (a = x.a,)
 
       s2, m2 = Optimisers.update(s, m, g)
       @test m[1] == 1:2  # not mutated
-      @test Optimisers.iswriteable(m[1])
+      @test Optimisers.maywrite(m[1])
       @test m2[1] ≈ [1,2] .- 0.1 .* [25, 33]
 
       s3, m3 = Optimisers.update!(s, m, g)