Repository navigation
feat: add support for lhs compiled nodes #26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 3 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,17 @@ | ||
| This is a history of changes to gateless/clara-rules. | ||
|
|
||
| # 1.8.0 | ||
| * `defrule` and `defquery` now compile their left-hand-side (LHS) expressions when the form is evaluated. An LHS that does not compile now fails at load time, not at `mk-session`. | ||
| * The compiled LHS fns are stored in the `:clara.rules/exprs` metadata of the rule or query var. `mk-session` uses them in place of `eval`. A node that several rules share uses one fn. | ||
| * A fn is matched by the condition data that its expression is built from. Rules built at runtime still use `eval`. A complex negation still uses `eval` for its generated condition. | ||
| * Deserialization of a rulebase uses the precompiled LHS and RHS fns when the rule namespaces are on the classpath. It loads those namespaces when needed. Otherwise it uses `eval`, as before. | ||
| * The serialized expression data now holds the `:handler` var symbol and the `:expr-key` of each precompiled expression. A rulebase serialized by an earlier version still deserializes with `eval`. | ||
| * Fix deserialization with `:compiler-cache false` when an expression still needs `eval`. Before, a `:cache-key` stored in the serialized data made it throw a `ClassCastException`. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I find this sentence to be confusing. Why is it holding this key still and why does it get a class-cast exception? |
||
| * `query` looks up a query that has a name by that name. A query var now works with a rulebase serialized by an earlier version, where the query map can differ. | ||
| * A `defquery` with params that its LHS does not bind now fails at load time. | ||
| * A `defquery` query map now has a `:handler` symbol that points to its var, as a rule map does. | ||
| * Precompiled fns are now used when `:compiler-cache` is `false`. Before, the precompiled RHS handler was used only when the compiler cache was enabled. | ||
|
|
||
| # 1.7.0 | ||
| * Add opt-in caching of rule right-hand-side (RHS) output across sessions. A rule opts in with a `:cache` prop; the caller passes a cache atom (any `clojure.core.cache/CacheProtocol`) as the `:activation-cache` option to `fire-rules`/`fire-rules-async`. On a cache hit the stored RHS output is replayed and the RHS is skipped; on a miss the RHS runs and its output is recorded. Firing without a cache is unchanged. Cache policy (TTL, eviction, hit/miss metrics) is the caller's responsibility. | ||
| * Add a `:activation-cache-key-fn` option to `fire-rules`/`fire-rules-async` that overrides the default activation cache key (`clara.rules.activation-cache.core/build-cache-key`). It receives the activation map (`{:node :token}`) and returns the key, or nil to skip caching for that activation (the RHS runs uncached). Only consulted when `:activation-cache` is supplied and the rule opted in; choosing a sound key is the caller's responsibility. | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -298,13 +298,15 @@ | |
| (:rhs production) | ||
| &env) | ||
| [rule-args & rule-body] (drop 2 rule-handler) | ||
| name-with-meta (vary-meta rule-name assoc :rule true :doc doc) | ||
| lhs-exprs (into {} (map (fn [[k form]] [(list 'quote k) form])) | ||
| (com/build-lhs-exprs rule-action)) ;;; The compiled LHS | ||
| name-with-meta (vary-meta rule-name assoc :rule true :doc doc :clara.rules/exprs lhs-exprs) | ||
| handler-name (symbol (name (ns-name *ns*)) (name rule-name))] ;;; The compiled RHS | ||
| `(defn ~name-with-meta | ||
| ([] | ||
| (assoc ~rule :handler '~handler-name)) | ||
| ([~@(take 1 rule-args)] | ||
| (~rule-name '?__token__ {})) | ||
| (~rule-name ~'?__token__ {})) | ||
|
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @mrrodriguez this is the fix we had discussed yesterday
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is OK, but you could also just do |
||
| ([~@rule-args] | ||
| ~@rule-body)))) | ||
|
|
||
|
|
@@ -318,10 +320,14 @@ | |
| [?issue <- ValidationError]) | ||
|
|
||
| See the [query authoring documentation](http://www.clara-rules.org/docs/queries/) for details." | ||
| [name & body] | ||
| (let [doc (if (string? (first body)) (first body) nil)] | ||
| `(def ~(vary-meta name assoc :query true :doc doc) | ||
| ~(dsl/build-query name body &env (meta &form))))) | ||
| [query-name & body] | ||
| (let [doc (if (string? (first body)) (first body) nil) | ||
| query (dsl/build-query query-name body &env (meta &form)) | ||
| lhs-exprs (into {} (map (fn [[k form]] [(list 'quote k) form])) | ||
| (com/build-lhs-exprs (update query :lhs second))) | ||
| handler-name (symbol (name (ns-name *ns*)) (name query-name))] | ||
| `(def ~(vary-meta query-name assoc :query true :doc doc :clara.rules/exprs lhs-exprs) | ||
| ~(assoc query :handler `'~handler-name)))) | ||
|
|
||
| (defmacro defhierarchy | ||
| "Defines a hierarchy and stores it in the given var. For instance, a simple hierarchy that adds | ||
|
|
||
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2128,7 +2128,7 @@ | |
|
|
||
| (defn- query* | ||
| [rulebase memory query params] | ||
| (let [query-node (get-in rulebase [:query-nodes query])] | ||
| (let [query-node (get-in rulebase [:query-nodes (or (:name query) query)])] ;;; lookup by name or value | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is a little bit weird because if the query actually has changed, it could even have different parameters now. However, you would be resolving it to whatever it used to be. So the call one would not really align anymore. |
||
| (when (= nil query-node) | ||
| (platform/throw-error (str "The query " query " is invalid or not included in the rule base."))) | ||
| (when-not (= (into #{} (keys params)) ;; nil params should be equivalent to #{} | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -96,15 +96,15 @@ | |
|
|
||
| (defquery temperature-below-value-using-symbol-arg | ||
| [?value] | ||
| [:temperature [{value :value}] (< value ?value)]) | ||
| [:temperature [{value :value}] (= ?value value)]) | ||
|
|
||
| (defquery temperature-below-value-using-keyword-arg | ||
| [:?value] | ||
| [:temperature [{value :value}] (< value ?value)]) | ||
| [:temperature [{value :value}] (= ?value value)]) | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Does Query no longer has name somantically for what it is doing. Why was the equals changed here? |
||
|
|
||
| (deftest test-query-definition-bindings-args | ||
| (testing "can define queries using symbol or keyword arguments" | ||
| (is (= (dissoc temperature-below-value-using-symbol-arg :name) (dissoc temperature-below-value-using-keyword-arg :name))))) | ||
| (is (= (dissoc temperature-below-value-using-symbol-arg :name :handler) (dissoc temperature-below-value-using-keyword-arg :name :handler))))) | ||
|
|
||
| (deftest test-query-param-args | ||
| (testing "noop query-params using keyword arguments" | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,155 @@ | ||
| (ns clara.test-lhs-exprs | ||
| "Tests for LHS expressions that defrule and defquery compile at load time. | ||
| Each var holds its compiled LHS fns in :clara.rules/exprs, keyed by condition data. | ||
| mk-session uses these fns in place of eval, and equal condition data shares one fn." | ||
| (:require [clara.rules :refer [defrule defquery mk-session insert insert! fire-rules query]] | ||
| [clara.rules.accumulators :as acc] | ||
| [clara.rules.dsl :as dsl] | ||
| [clara.rules.engine :as eng] | ||
| [clara.rules.testfacts :refer [->Temperature ->WindSpeed ->Cold]] | ||
| [clojure.set :as set] | ||
| [clojure.test :refer [deftest is testing]]) | ||
| (:import [clara.rules.testfacts Temperature WindSpeed Cold])) | ||
|
|
||
| (defrule cold-rule | ||
| [Temperature (< temperature 0) (= ?t temperature)] | ||
| => | ||
| (insert! (->Cold ?t))) | ||
|
|
||
| (defrule cold-and-windy-rule | ||
| [Temperature (< temperature 0) (= ?t temperature)] | ||
| [WindSpeed (< ?t windspeed)] | ||
| [:test (some? ?t)] | ||
| => | ||
| (insert! (->Cold (dec ?t)))) | ||
|
|
||
| (defrule exists-rule | ||
| [:exists [Temperature (< temperature 0)]] | ||
| [WindSpeed (= ?w windspeed)] | ||
| => | ||
| (insert! (->Cold ?w))) | ||
|
|
||
| (defquery cold-count-query | ||
| [] | ||
| [?n <- (acc/count) :from [Cold]]) | ||
|
|
||
| (defrule complex-negation-rule | ||
| [Temperature (= ?t temperature)] | ||
| [:not [:or [WindSpeed (= ?t windspeed)] | ||
| [Cold (= ?t temperature)]]] | ||
| => | ||
| (insert! (->Cold (* 10 ?t)))) | ||
|
|
||
| (defquery cold-query | ||
| [] | ||
| [Cold (= ?t temperature)]) | ||
|
|
||
| (defrule temperature-and-cold-rule | ||
| [Temperature (= ?t temperature)] | ||
| [Cold (= ?t temperature)] | ||
| => | ||
| nil) | ||
|
|
||
| (defquery temperature-query | ||
| [] | ||
| [Temperature (= ?t temperature)]) | ||
|
|
||
| (defn- precompiled-fns | ||
| [& vars] | ||
| (set (mapcat (comp vals :clara.rules/exprs meta) vars))) | ||
|
|
||
| (defn- expr-fns | ||
| "Returns {expr-node-type #{fn}} for the compiled expressions of a session." | ||
| [session] | ||
| (reduce-kv (fn [m [_ expr-node-type] [f]] | ||
| (update m expr-node-type (fnil conj #{}) f)) | ||
| {} | ||
| (-> session eng/components :rulebase :node-expr-fn-lookup))) | ||
|
|
||
| (defn- eval-in-scratch-ns | ||
| [form] | ||
| (binding [*ns* (create-ns 'clara.test-lhs-exprs.scratch)] | ||
| (refer-clojure) | ||
| (eval form))) | ||
|
|
||
| (deftest test-lhs-error-at-load-time | ||
| (testing "an LHS that does not compile fails when defrule is evaluated" | ||
| (is (thrown? Exception | ||
| (eval-in-scratch-ns | ||
| '(clara.rules/defrule bad-rule | ||
| [clara.rules.testfacts.Temperature (= ?t (no-such-fn temperature))] | ||
| => | ||
| nil))))) | ||
| (testing "an LHS that does not compile fails when defquery is evaluated" | ||
| (is (thrown? Exception | ||
| (eval-in-scratch-ns | ||
| '(clara.rules/defquery bad-query | ||
| [] | ||
| [clara.rules.testfacts.Temperature (= ?t (no-such-fn temperature))])))))) | ||
|
|
||
| (deftest test-precompiled-lhs-fns-are-used | ||
| (let [session (mk-session [cold-rule cold-and-windy-rule exists-rule cold-count-query] | ||
| :cache false | ||
| :compiler-cache false) | ||
| precompiled (precompiled-fns #'cold-rule #'cold-and-windy-rule #'exists-rule #'cold-count-query) | ||
| fns (expr-fns session)] | ||
| (testing "every expression type of these productions is present" | ||
| (is (= #{:alpha-expr :join-filter-expr :test-expr :accum-expr :action-expr} | ||
| (set (keys fns))))) | ||
| (testing "each LHS fn is a precompiled fn, even with the compiler cache disabled" | ||
| (doseq [expr-node-type [:alpha-expr :join-filter-expr :test-expr :accum-expr] | ||
| f (get fns expr-node-type)] | ||
| (is (contains? precompiled f) (str expr-node-type " was not precompiled")))) | ||
| (testing "each RHS fn is the rule var, even with the compiler cache disabled" | ||
| (is (set/subset? #{#'cold-rule #'cold-and-windy-rule #'exists-rule} | ||
| (:action-expr fns)))) | ||
| (testing "the session gives the expected results" | ||
| (is (= [{:?n 3}] | ||
| (-> session | ||
| (insert (->Temperature -5 "MCI") (->WindSpeed 10 "MCI")) | ||
| (fire-rules) | ||
| (query cold-count-query))))))) | ||
|
|
||
| (deftest test-shared-condition-uses-one-fn | ||
| (let [session (mk-session [cold-rule cold-and-windy-rule] :cache false) | ||
| temperature-alphas (-> session eng/components :rulebase :alpha-roots (get Temperature))] | ||
| (testing "both rules share the alpha node of the Temperature condition" | ||
| (is (= 1 (count temperature-alphas)))) | ||
| (testing "the shared node uses the precompiled fn of one of the rules" | ||
| (is (contains? (precompiled-fns #'cold-rule #'cold-and-windy-rule) | ||
| (:activation (first temperature-alphas))))))) | ||
|
|
||
| (deftest test-fact-type-is-part-of-the-key | ||
| (testing "one rule keeps a fn for each fact type when the constraints are equal" | ||
| (let [precompiled (precompiled-fns #'temperature-and-cold-rule) | ||
| alpha-fns (:alpha-expr (expr-fns (mk-session [temperature-and-cold-rule] :cache false)))] | ||
| (is (= 2 (count precompiled) (count alpha-fns))) | ||
| (is (every? precompiled alpha-fns)))) | ||
| (testing "conditions that differ only in the fact type keep their own fns" | ||
| (let [session (-> (mk-session [cold-query temperature-query] :cache false) | ||
| (insert (->Cold 1) (->Temperature 2 "MCI")) | ||
| (fire-rules))] | ||
| (is (= [{:?t 1}] (query session cold-query))) | ||
| (is (= [{:?t 2}] (query session temperature-query)))))) | ||
|
|
||
| (deftest test-expr-keys-hold-no-classes | ||
| (testing "a key holds class names, so it reads back from serialized data before the fact classes are loaded" | ||
| (is (not-any? class? | ||
| (mapcat #(tree-seq coll? seq %) | ||
| (keys (:clara.rules/exprs (meta #'cold-and-windy-rule)))))))) | ||
|
|
||
| (deftest test-fallback-to-eval | ||
| (testing "a complex negation still compiles and fires" | ||
| (is (= [{:?t 30}] | ||
| (-> (mk-session [complex-negation-rule cold-query] :cache false) | ||
| (insert (->Temperature 3 "MCI")) | ||
| (fire-rules) | ||
| (query cold-query))))) | ||
| (testing "a rule built at runtime has no var and still compiles and fires" | ||
| (let [rule (dsl/parse-rule [[Temperature (= ?t temperature)]] | ||
| (insert! (->Cold ?t)))] | ||
| (is (= [{:?t 7}] | ||
| (-> (mk-session [rule cold-query] :cache false) | ||
| (insert (->Temperature 7 "MCI")) | ||
| (fire-rules) | ||
| (query cold-query))))))) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why metadata instead of first class data on the data structure?