infrastate — org.clojars.w-se/infrastate 0.0.6

all-interceptors clj

(all-interceptors fn-or-fns)

bare-resource-fn clj

(bare-resource-fn wrapped-or-bare allow-bare)

call-all! clj

(call-all! fn-or-fns)

flat-list-of-fns clj

(flat-list-of-fns fn-or-brood)

spawn clj

(spawn initial-state
       brood-or-fn
       &
       {:keys [do-before do-after do-before-all do-after-all before after
               after-iteration before-all after-all allow-bare max-iterations
               return-val]
        :or {do-after (constantly nil)
             before identity
             after-iteration identity
             do-before identity
             after-all identity
             allow-bare false
             max-iterations 1000
             do-after-all (constantly nil)
             before-all identity
             after identity
             do-before-all (constantly nil)
             return-val :state}})

Takes the initial state (a map) and a list of 'functions of state' called brood, builds the composition of all those functions (called 'everything') and repeatedly applies it (everything) to its previous result until nothing changes anymore or the upper limit of iterations is reached. This is a fixed-point iteration. spawn signals with ::outcome :complete or ::outcome :partial if the fixed-point was reached or if it ran into the limit.

Examples: (spawn {:x 0} #(assoc % :x 100) :allow-bare true) => {:x 100, :infrastate/outcome :complete, :infrastate/iterations 1}

(spawn {:x 0} #(update % :x dec) :allow-bare true) => {:x -1001, :infrastate/outcome :partial, :infrastate/iterations 1000}

(spawn {:x 5} #(if (> (:x %) 10) % (update % :x inc)) :allow-bare true) => {:x 11, :infrastate/outcome :complete, :infrastate/iterations 6}

(spawn {:x 10} (constantly nil) :allow-bare true) => #:infrastate{:outcome :complete, :iterations 1}

Parameters:

initial-state: a map with the input for the first iteration brood-or-fn: a single function or a list of functions

You can inject function calls by using hooks and interceptors. Hooks start with do-. They are called for side effects and their return value is ignored. do-before/do-after are called directly before every fn in the brood, do-before-all/do-after-all only once per call to spawn.

Every hook function receives a map with different versions of the state from different point in time.

:before refers to the state right before this hook point (i.e. right before a brood fn is applied)

:initial refers to the initial-state as passed to the first arg of spawn

:first refers to the initial state after applying the before-all fns to it

:current refers to the most recent version of the state right before the hook point

Interceptors are called for their return value.

before-all is passed the initial state (as passed per argument to spawn) and it returns the first-state, which is the first state that will be used in the fixpoint iteration.

after-all receives the last-state of the iterations and returns the final-state.

--

With max-iterations you can limit the amount of iterations until spawn considers the state to be unstable. If state stablizes with less iterations than max-iterations, the outcome will be :complete. If it reaches max-iterations, outcome will be :partial. Default is 1000.

Note, that :max-iterations 0 will still run the code once!

--

:return-val can be used to control what spawn returns. With the default value of :state, it returns the most recent state when spawn terminates, that is the final-state when it completes or the latest partial-state when it runs into :max-iterations. after and after-all interceptors are applied to this result.

If you pass :succession to this key, it will instead return a sequence of all states, beginning with the last state, working your way up to the initial state.