commit 2ad806a8fcc0754413b15fa2bd894fb6bcef6e6e Author: Jeremy Penner Date: Wed May 6 09:36:01 2015 -0400 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..816887c --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +/target +/classes +/checkouts +pom.xml +pom.xml.asc +*.jar +*.class +/.lein-* +/.nrepl-port +.DS_Store \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7689f30 --- /dev/null +++ b/LICENSE @@ -0,0 +1,214 @@ +THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC +LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM +CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + +a) in the case of the initial Contributor, the initial code and +documentation distributed under this Agreement, and + +b) in the case of each subsequent Contributor: + +i) changes to the Program, and + +ii) additions to the Program; + +where such changes and/or additions to the Program originate from and are +distributed by that particular Contributor. A Contribution 'originates' from +a Contributor if it was added to the Program by such Contributor itself or +anyone acting on such Contributor's behalf. Contributions do not include +additions to the Program which: (i) are separate modules of software +distributed in conjunction with the Program under their own license +agreement, and (ii) are not derivative works of the Program. + +"Contributor" means any person or entity that distributes the Program. + +"Licensed Patents" mean patent claims licensable by a Contributor which are +necessarily infringed by the use or sale of its Contribution alone or when +combined with the Program. + +"Program" means the Contributions distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement, +including all Contributors. + +2. GRANT OF RIGHTS + +a) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free copyright license to +reproduce, prepare derivative works of, publicly display, publicly perform, +distribute and sublicense the Contribution of such Contributor, if any, and +such derivative works, in source code and object code form. + +b) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free patent license under +Licensed Patents to make, use, sell, offer to sell, import and otherwise +transfer the Contribution of such Contributor, if any, in source code and +object code form. This patent license shall apply to the combination of the +Contribution and the Program if, at the time the Contribution is added by the +Contributor, such addition of the Contribution causes such combination to be +covered by the Licensed Patents. The patent license shall not apply to any +other combinations which include the Contribution. No hardware per se is +licensed hereunder. + +c) Recipient understands that although each Contributor grants the licenses +to its Contributions set forth herein, no assurances are provided by any +Contributor that the Program does not infringe the patent or other +intellectual property rights of any other entity. Each Contributor disclaims +any liability to Recipient for claims brought by any other entity based on +infringement of intellectual property rights or otherwise. As a condition to +exercising the rights and licenses granted hereunder, each Recipient hereby +assumes sole responsibility to secure any other intellectual property rights +needed, if any. For example, if a third party patent license is required to +allow Recipient to distribute the Program, it is Recipient's responsibility +to acquire that license before distributing the Program. + +d) Each Contributor represents that to its knowledge it has sufficient +copyright rights in its Contribution, if any, to grant the copyright license +set forth in this Agreement. + +3. REQUIREMENTS + +A Contributor may choose to distribute the Program in object code form under +its own license agreement, provided that: + +a) it complies with the terms and conditions of this Agreement; and + +b) its license agreement: + +i) effectively disclaims on behalf of all Contributors all warranties and +conditions, express and implied, including warranties or conditions of title +and non-infringement, and implied warranties or conditions of merchantability +and fitness for a particular purpose; + +ii) effectively excludes on behalf of all Contributors all liability for +damages, including direct, indirect, special, incidental and consequential +damages, such as lost profits; + +iii) states that any provisions which differ from this Agreement are offered +by that Contributor alone and not by any other party; and + +iv) states that source code for the Program is available from such +Contributor, and informs licensees how to obtain it in a reasonable manner on +or through a medium customarily used for software exchange. + +When the Program is made available in source code form: + +a) it must be made available under this Agreement; and + +b) a copy of this Agreement must be included with each copy of the Program. + +Contributors may not remove or alter any copyright notices contained within +the Program. + +Each Contributor must identify itself as the originator of its Contribution, +if any, in a manner that reasonably allows subsequent Recipients to identify +the originator of the Contribution. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities with +respect to end users, business partners and the like. While this license is +intended to facilitate the commercial use of the Program, the Contributor who +includes the Program in a commercial product offering should do so in a +manner which does not create potential liability for other Contributors. +Therefore, if a Contributor includes the Program in a commercial product +offering, such Contributor ("Commercial Contributor") hereby agrees to defend +and indemnify every other Contributor ("Indemnified Contributor") against any +losses, damages and costs (collectively "Losses") arising from claims, +lawsuits and other legal actions brought by a third party against the +Indemnified Contributor to the extent caused by the acts or omissions of such +Commercial Contributor in connection with its distribution of the Program in +a commercial product offering. The obligations in this section do not apply +to any claims or Losses relating to any actual or alleged intellectual +property infringement. In order to qualify, an Indemnified Contributor must: +a) promptly notify the Commercial Contributor in writing of such claim, and +b) allow the Commercial Contributor tocontrol, and cooperate with the +Commercial Contributor in, the defense and any related settlement +negotiations. The Indemnified Contributor may participate in any such claim +at its own expense. + +For example, a Contributor might include the Program in a commercial product +offering, Product X. That Contributor is then a Commercial Contributor. If +that Commercial Contributor then makes performance claims, or offers +warranties related to Product X, those performance claims and warranties are +such Commercial Contributor's responsibility alone. Under this section, the +Commercial Contributor would have to defend claims against the other +Contributors related to those performance claims and warranties, and if a +court requires any other Contributor to pay any damages as a result, the +Commercial Contributor must pay those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON +AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER +EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR +CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A +PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all risks +associated with its exercise of rights under this Agreement , including but +not limited to the risks and costs of program errors, compliance with +applicable laws, damage to or loss of data, programs or equipment, and +unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY +CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION +LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY +OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of the +remainder of the terms of this Agreement, and without further action by the +parties hereto, such provision shall be reformed to the minimum extent +necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Program itself +(excluding combinations of the Program with other software or hardware) +infringes such Recipient's patent(s), then such Recipient's rights granted +under Section 2(b) shall terminate as of the date such litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it fails to +comply with any of the material terms or conditions of this Agreement and +does not cure such failure in a reasonable period of time after becoming +aware of such noncompliance. If all Recipient's rights under this Agreement +terminate, Recipient agrees to cease use and distribution of the Program as +soon as reasonably practicable. However, Recipient's obligations under this +Agreement and any licenses granted by Recipient relating to the Program shall +continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, but in +order to avoid inconsistency the Agreement is copyrighted and may only be +modified in the following manner. The Agreement Steward reserves the right to +publish new versions (including revisions) of this Agreement from time to +time. No one other than the Agreement Steward has the right to modify this +Agreement. The Eclipse Foundation is the initial Agreement Steward. The +Eclipse Foundation may assign the responsibility to serve as the Agreement +Steward to a suitable separate entity. Each new version of the Agreement will +be given a distinguishing version number. The Program (including +Contributions) may always be distributed subject to the version of the +Agreement under which it was received. In addition, after a new version of +the Agreement is published, Contributor may elect to distribute the Program +(including its Contributions) under the new version. Except as expressly +stated in Sections 2(a) and 2(b) above, Recipient receives no rights or +licenses to the intellectual property of any Contributor under this +Agreement, whether expressly, by implication, estoppel or otherwise. All +rights in the Program not expressly granted under this Agreement are +reserved. + +This Agreement is governed by the laws of the State of New York and the +intellectual property laws of the United States of America. No party to this +Agreement will bring a legal action under this Agreement more than one year +after the cause of action arose. Each party waives its rights to a jury trial +in any resulting litigation. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4cbdd46 --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# exav - EXecution As a Value + +## Why? + +The fundamental building block of Clojure is the immutable value. Values can be shared, values can be saved, values can be inspected, values can be transformed. + +Programs often must ask for input from the external world. exav models this much like core.async; we write code which looks very much like a simple function which is producing a value, except that sprinkled throughout are operations which cause execution to be suspended until some external event takes place to supply us with a new value. + +core.async is wonderful, but its fundamental building block is the channel, which is not a value. We have no way of looking inside the computation which is suspended. We have no way of rewinding it. We have no way of persisting it. core.async code builds up a black box, to be fed with data. + +I want the ability to rewind time, hotload new code, then run time forward again. I want the ability to script complex interactions in a game that take place over arbitrary amounts of time, and for my entire game state to exist in a map that can be saved as EDN or Transit. exav gives me the tools to do this. + +## Usage + +exav currently has one basic building block: the `proc` macro. The `proc` macro works very much like the `go` macro in core.async, except that instead of returning a channel, it returns a function, and instead of blocking on `>!` or ` :name + + ; calling a proc with two arguments continues the process + ; you must pass the state returned by the proc, and the value to be returned by (wait) + state2 (p state "Bob") + + ; if the :result key exists, it will be the only thing in the map, and is equal to the + ; final return value of the proc + result (:result state2) ; => "Hello, Bob" + + ; note that it is completely legal to hold onto and re-use old states! + result2 (:result (p state "Phil")) ; => "Hello, Phil" + + ; a proc can also be called with just one argument, which is the same as passing nil + ; for the second argument + result3 (:result (p state)) ; => "Hello, " + ]) + +`wait` always takes a single argument; a value that describes what the proc is waiting for. + +## License + +Copyright © 2014 Jeremy Penner + +Distributed under the Eclipse Public License either version 1.0 or (at +your option) any later version. diff --git a/doc/intro.md b/doc/intro.md new file mode 100644 index 0000000..a8a60a1 --- /dev/null +++ b/doc/intro.md @@ -0,0 +1,3 @@ +# Introduction to exav + +TODO: write [great documentation](http://jacobian.org/writing/what-to-write/) diff --git a/project.clj b/project.clj new file mode 100644 index 0000000..fb62874 --- /dev/null +++ b/project.clj @@ -0,0 +1,7 @@ +(defproject exav "0.1.0-SNAPSHOT" + :description "EXecution As a Value, flexible tools for async" + :url "http://example.com/FIXME" + :license {:name "Eclipse Public License" + :url "http://www.eclipse.org/legal/epl-v10.html"} + :dependencies [[org.clojure/clojure "1.6.0"] + [org.clojure/core.async "0.1.346.0-17112a-alpha"]]) diff --git a/src/clj/exav/core.clj b/src/clj/exav/core.clj new file mode 100644 index 0000000..63a2eaf --- /dev/null +++ b/src/clj/exav/core.clj @@ -0,0 +1,78 @@ +(ns exav.core + (:require [clojure.core.async.impl.ioc-macros :as ioc])) + +;; Goal: +;; Convert an arbitrary clojure form that contains "blocking" calls, to a function which +;; accepts a state and an argument (the result of the blocking call) and returns the next +;; state and a "blocking" value. This state can then be persisted, arbitrarily rolled back, +;; and re-run; it is a simple clojure value. No hidden local state is generated. + +; "machine" is a mutable array of objects used by the core.async ioc-macros to implement +; the state machine. standard indices into the array are used to implement various fields +; (what state is running, the value of the previous expression, etc) + +; We extend this with two extra fields - WAITFOR-IDX, which stores the value passed to (wait), +; and WAITFOR-FLAG-IDX, which is set to true when (wait) is called, so that we can tell the +; difference between a final return and (wait nil). +(def ^:const WAITFOR-IDX ioc/USER-START-IDX) +(def ^:const WAITFOR-FLAG-IDX (+ ioc/USER-START-IDX 1)) +(def ^:const LOCALS-START-IDX (+ ioc/USER-START-IDX 2)) + +(defn wait [ev] + (assert nil "wait must be used in an proc block")) + +(defn wait* [machine nextblock ev] + "The function called to implement our custom terminator (last statement in a 'block') + when the state machine is running. Returns nil to signal that the state machine should + suspend execution (the other option is :recur, which would immediately move on to the + next block)" + (ioc/aset-all! machine WAITFOR-IDX ev + WAITFOR-FLAG-IDX true + ioc/STATE-IDX nextblock) + nil) + +(defn config-machine [machine state value] + "Takes apart a state map as returned from a proc, and sets up all the values in an empty + machine array to allow it to continue. Returns the state's thread bindings, basically just + to pass to run-machine, because they are the only thing we need to configure whether or not + we have a state." + (assert (and (integer? (:state state)) + (vector? (:locals state))) + "state is not valid") + + ; copy locals + (doseq [[i local] (map vector (iterate inc LOCALS-START-IDX) (:locals state))] + (ioc/aset-object machine i local)) + + (ioc/aset-all! machine + ; copy next state + ioc/STATE-IDX (:state state) + ; copy argument + ioc/VALUE-IDX value) + (:bindings state)) + +(defn run-machine [machine bindings] + "Given a machine array and thread bindings, runs the machine until it finishes or blocks, + and returns a new state map with the results." + (let [bindings (or bindings (clojure.lang.Var/getThreadBindingFrame))] + (ioc/aset-all! machine ioc/BINDINGS-IDX bindings) + (ioc/run-state-machine machine) + (if (ioc/aget-object machine WAITFOR-FLAG-IDX) + ; blocked + {:bindings bindings + :locals (vec (for [i (range LOCALS-START-IDX (.length machine))] + (ioc/aget-object machine i))) + :state (ioc/aget-object machine ioc/STATE-IDX) + :waitfor (ioc/aget-object machine WAITFOR-IDX)} + ; complete + {:result (ioc/aget-object machine ioc/VALUE-IDX)}))) + +(defmacro proc [& body] + `(let [machine-fn# ~(ioc/state-machine `(do ~@body) 2 (keys &env) {`wait `wait*})] + (fn proc# + ([] (run-machine (machine-fn#) nil)) + ([state#] (proc# state# nil)) + ([state# value#] + (let [machine# (machine-fn#) + bindings# (config-machine machine# state# value#)] + (run-machine machine# bindings#)))))) diff --git a/src/clj/exav/perfunct.clj b/src/clj/exav/perfunct.clj new file mode 100644 index 0000000..f1e7a26 --- /dev/null +++ b/src/clj/exav/perfunct.clj @@ -0,0 +1,120 @@ +(ns exav.perfunct) + +; Persistable functions: +; A function in clojure is a first-class value that can be passed around and composed. +; It can't, however, be sensibly persisted, except in ad-hoc ways. In general, there +; is not much of a use-case for persisting arbitrary functions. We don't really ever +; want to be given an arbitrary block of clojure code, compile it, and run it - that's +; a security disaster. It would often be nice, however, to have a first-class way of +; _referring_ to a particular set of whitelisted functions, and be able to write down +; and read those _references_. + +; One could concievably just persist a clojure var, but that has its own set of problems. +; Chief among them is that you would still require a whitelist to ensure that you're not +; being tricked into calling "evil" functions in places that you didn't expect. +; Another significant problem is that you lose any particular ability to use or persist +; a closure. + +; perfunct provides a simple solution to these problems. We introduce an object called +; a peref (for "persistable reference"), which contains a simple value used to refer to +; the function, can be directly called like a function (much like a var), and derefed (if +; it is referring to a non-function unpersistable thing, such as an atom or channel). +; We provide built-in hooks for pr-str and transit serialization, reader literals, and +; functions for extracting a peref's value as clojure data. + +; In addition to persisting references to functions, we can use this flexible +; functionality to persist references to atoms, to core.async channels, to expensive +; objects that should be instantiated lazily, or even to resources meant to be loaded +; from disk. + +; definvokable adapted from code by Meikel Brandmeyer +; https://groups.google.com/forum/#!topic/clojure/pl4HgR9L_lg +(def max-arities 20) + +(defmacro definvokable + [type fields f & deftype-tail] + (let [args (repeatedly max-arities gensym) + arity (fn [n] + (let [args (take n args)] + `(invoke [this# ~@args] (~f this# ~@args)))) + vararg `(invoke [this# ~@args more#] + (apply ~f this# ~@args more#)) + apply-to `(applyTo [this# args#] (apply ~f this# args#))] + `(deftype ~type + ~fields + clojure.lang.IFn + ~@(map arity (range (inc max-arities))) + ~vararg + ~apply-to + ~@deftype-tail))) + +(defn invoke-peref [peref & args] (apply @peref args)) +(definvokable Peref [lookup name params] invoke-peref + clojure.lang.IDeref + (deref [_] (apply (.lookup-fn lookup) name params))) + +(defn invoke-peref-lookup [lookup name & args] (->Peref lookup name args)) +(definvokable PerefLookup [id lookup-fn] invoke-peref-lookup) + +(defn peref-tag [p] + (let [id (.id (.lookup p))] + (str (namespace id) "/" (name id)))) + +(defn peref-data [p] + (let [name (.name p) + params (.params p)] + (vec (cons name params)))) + +(defmethod print-method Peref [v ^java.io.Writer w] + "Print an edn literal for a Peref" + (let [tag (str "#" (peref-tag v) " ")] + (.write w tag) + (print-method (peref-data v) w))) + +(defn cached [lookup-fn] + "Takes the result of a lookup-fn and memoizes it. Also provides a function, + accessed by looking up :clear-cache, which clears the cache completely if called + with no arguments, and clears the cache for a particular peref when called with + its arguments." + (let [cache (atom {}) + clear-cache + (fn ([] (reset! cache {})) + ([peref] (swap! cache #(dissoc % (peref-data peref)))))] + (fn [& args] + (if (= (first args) :clear-cache) + (apply clear-cache (rest args)) + (if (contains? @cache args) + (get @cache args) + (let [v (apply lookup-fn (vec args))] + (swap! cache #(assoc % args v)) + v)))))) + +(defn partial-map [fn-map] + "Takes a map of the form {name fn} and returns a lookup function which + takes a name and the arguments to pass to fn and returns the fn. + It is legal for the value to not be a function so long as the lookup + is not passed any extra arguments besides the name." + (fn [name & args] + (let [fn (get fn-map name)] + (if fn + (apply partial fn args) + nil)))) + +(defn compose-lookup [& lookup-fns] + "Returns a lookup-fn which calls each of the passed-in lookup-fns in turn, + returning the first non-nil result." + (fn [& args] + (loop [lookup-fns lookup-fns] + (if (seq lookup-fns) + (let [lookup-fn (first lookup-fns) + v (apply lookup-fn args)] + (if (nil? v) + (recur (rest lookup-fns)) + v)))))) + +(defn lookup [id & lookup-fns] + "Creates a peref lookup function, identified by a namespaced symbol, which is + used to create peref objects. Simply call the result with the arguments to pass + to your lookup-fns, and it will return a peref object that will call your lookup-fns + when derefed." + (->PerefLookup id (apply compose-lookup lookup-fns))) diff --git a/test/exav/core_test.clj b/test/exav/core_test.clj new file mode 100644 index 0000000..d6a080d --- /dev/null +++ b/test/exav/core_test.clj @@ -0,0 +1,7 @@ +(ns exav.core-test + (:require [clojure.test :refer :all] + [exav.core :refer :all])) + +(deftest a-test + (testing "FIXME, I fail." + (is (= 0 1))))