managed_iteration suggestion

[tbreloff]

Currently a managed iteration takes the form:

function managed_iteration!{T<:AbstractArray}(f!::Base.Callable,
                                              mgr::IterationManager,
                                              dest::T,
                                              istate::IterationState{T};
                                              by::Base.Callable=default_by)
    pre_hook(mgr, istate)

    while !(finished(mgr, istate))
        f!(dest, istate.prev)
        update!(istate, dest; by=by)
        iter_hook(mgr, istate)
    end

    post_hook(mgr, istate)
    istate
end

but I think it will be more general if the dest and f!(dest, istate.prev) happen inside the update! call. I may not have a single parameter vector that I want to update in this fashion, and it may be non-trivial or inefficient to make a f! method of this form.

My proposal:

function managed_iteration!(mgr::IterationManager, istate::IterationState)
    pre_hook(mgr, istate)

    while !(finished(mgr, istate))
        update!(mgr, istate)
        iter_hook(mgr, istate)
    end

    post_hook(mgr, istate)
    istate
end

We can add convenience managers/states to reproduce the same form above, but the core loop is more general. Also, we can just have both forms and let multiple dispatch work.

[sglyon]

@tbreloff thanks for the idea -- overall I like it.

As a little background, my initial goal with the package was to do two things:

1. Provide mechanisms that are as general as possible and...
2. Wrap these mechanisms in a way that exposes APIs that range from very automatic (like that one-line version of Newton's method example in the read me) to giving the user 100% control over whatever aspects he/she wants to customize.

I think the current version I have does well at bringing out the "automatic" part of point (2) as it doesn't require the user to define their own types and abstracts away how instances of IterationManager and IterationState need to interact.

I think your proposal does better at both point (1) -- being more general -- and the full control part of point (2). With that in mind I think we should definitely pursue something like what you proposed here.

Aside: I'm fairly happy with those 2 design goals, but would be happy to hear suggestions for revisions. I think clear design goals are important as I feel that once we have those, building the API around them should be easier.

[tbreloff]

+1 to your design goals. I won't have much time this week, but I'll prepare a PR to add this when I have a chance. I'll keep what you have already and will only remove it if/when I have a feature-complete replacement. Thanks.