Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
This is a history of changes to gateless/clara-rules.

# 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 `: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.
* `fire-rules-async` now runs synchronous RHS bodies on the async executor rather than the calling thread (previously only asynchronous results were deferred). Dynamic bindings are conveyed, so behavior is unchanged for RHS bodies that do not depend on running on the calling thread specifically.
* Add a `:default-props` option to `mk-session`/`defsession`: a map of rule properties merged into every rule (productions with an `:rhs`; queries are unaffected), beneath each rule's own props. Precedence is session-default < namespace-level < rule-level, so a rule can override or opt out (e.g. `{:cache false}`). For example, `:default-props {:cache true}` enables activation caching for all rules by default.
Comment thread
k13gomez marked this conversation as resolved.
Resolved
* Upgrade futurama to 1.4.7.

# 1.6.8
* Rule-level properties now take precedence over namespace-level properties when both define the same key (previously namespace properties overrode rule-level properties).
* Add `:cache` to the default set of allowed namespace-level rule properties (now `:author :cache :no-loop :salience`).
Expand Down
2 changes: 1 addition & 1 deletion deps.edn
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
:ensure "target/main/classes"}
:deps {org.clojure/clojure {:mvn/version "1.12.5"}
org.clojure/core.cache {:mvn/version "1.2.263"}
com.github.gateless/futurama {:mvn/version "1.4.6"}
com.github.gateless/futurama {:mvn/version "1.4.7"}
com.cnuernber/ham-fisted {:mvn/version "3.029"}
prismatic/schema {:mvn/version "1.4.1"}
org.clojure/data.fressian {:mvn/version "1.1.1"}}
Expand Down
6 changes: 3 additions & 3 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
<groupId>com.github.gateless</groupId>
<artifactId>clara-rules</artifactId>
<name>clara-rules</name>
<version>1.6.8</version>
<version>1.7.0</version>
<scm>
<tag>1.6.8</tag>
<tag>1.7.0</tag>
<url>https://github.com/gateless/clara-rules</url>
<connection>scm:git:git://github.com/gateless/clara-rules.git</connection>
<developerConnection>scm:git:ssh://git@github.com/gateless/clara-rules.git</developerConnection>
Expand All @@ -32,7 +32,7 @@
<dependency>
<groupId>com.github.gateless</groupId>
<artifactId>futurama</artifactId>
<version>1.4.6</version>
<version>1.4.7</version>
</dependency>
<dependency>
<groupId>org.clojure</groupId>
Expand Down
23 changes: 21 additions & 2 deletions src/main/clojure/clara/rules.clj
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,14 @@
other out and avoid operations deeper in the rules network. The behavior of unconditional insertions and RHS (right-hand side) retractions
is undefined when this option is enabled and this option should not be used when calling fire-rules can result in these operations.
Note that this is purely a performance optimization and no guarantees are made at this time on whether a given rule's RHS will be called.
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions."
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions.

:cache <atom> (NEW, subject to change/updates in the future):
An atom wrapping a clojure.core.cache/CacheProtocol implementation, used to cache rule right-hand-side (RHS) output across sessions.
A rule opts in via its own :cache prop (see clara.rules.activation-cache.core). 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 under the activation's key. Firing without a cache is unchanged;
the value must be a valid cache atom, and supplying anything else is unsupported and may throw. Cache policy (TTL, eviction, hit/miss metrics)
is the responsibility of the caller's cache implementation."
([session] (eng/fire-rules session {}))
([session opts] (eng/fire-rules session opts)))

Expand All @@ -58,7 +65,14 @@
other out and avoid operations deeper in the rules network. The behavior of unconditional insertions and RHS (right-hand side) retractions
is undefined when this option is enabled and this option should not be used when calling fire-rules can result in these operations.
Note that this is purely a performance optimization and no guarantees are made at this time on whether a given rule's RHS will be called.
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions."
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions.

:cache <atom> (NEW, subject to change/updates in the future):
An atom wrapping a clojure.core.cache/CacheProtocol implementation, used to cache rule right-hand-side (RHS) output across sessions.
A rule opts in via its own :cache prop (see clara.rules.activation-cache.core). 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 under the activation's key. Firing without a cache is unchanged;
the value must be a valid cache atom, and supplying anything else is unsupported and may throw. Cache policy (TTL, eviction, hit/miss metrics)
is the responsibility of the caller's cache implementation."
([session] (eng/fire-rules-async session {}))
([session opts] (eng/fire-rules-async session opts)))

Expand Down Expand Up @@ -214,6 +228,11 @@
information might prove useful for debugging compilation errors within the rulebase, eg. rulebase serialization
(ie. via Clara's durability support).
Defaults to true, see clara.rules.compiler/omit-compile-ctx-default for more information.
* :default-props - A map of rule properties merged into every rule (productions with an :rhs; queries are unaffected).
Comment thread
k13gomez marked this conversation as resolved.
Resolved
The defaults sit beneath each rule's own props, so precedence is session-default < namespace-level < rule-level; a rule
can override or opt out of a default (eg. a rule with {:cache false} stays false even when :default-props is {:cache true}).
For example, :default-props {:cache true} enables activation caching (see the :cache prop) for all rules by default.
This option also applies to defsession, which delegates to the same session creation.

This is not supported in ClojureScript, since it requires eval to dynamically build a session. ClojureScript
users must use pre-defined rule sessions using defsession."
Expand Down
32 changes: 32 additions & 0 deletions src/main/clojure/clara/rules/activation_cache/core.clj
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
(ns clara.rules.activation-cache.core
"Support for caching the output of rule right-hand-side (RHS) activations
so it can be replayed across rules sessions instead of recomputed.

The engine consults a cache the caller supplies via the `:cache` fire-rules
option: an atom wrapping any `clojure.core.cache/CacheProtocol` implementation.
A rule opts in via its own `:cache` prop. This namespace provides
`build-cache-key`, which derives the key an activation is cached under. Any
policy beyond basic lookup/hit/miss — TTL, tracking which entries were
consulted, sweeping at the end of a run — is the responsibility of the caller's
cache implementation.")

(defn build-cache-key
Comment thread
k13gomez marked this conversation as resolved.
Resolved
"Builds an activation cache key for the given activation (a map with `:node` and
`:token`).

The key is the data the RHS output depends on: the rule's environment, name,
props, and the bindings it fired on. The rule name and namespace version are
already encoded in the rule's `:name`/`:props` by the caller, so this key
changes exactly when the rule logic or its inputs change. The full bindings are
stored (not a hash) so a deserialized key compares `=` to a freshly-computed
one with no chance of collision."
[{:keys [node token]}]
(let [{:keys [production]} node
{:keys [bindings]} token
rule-name (:name production)
rule-env (or (:env production) {})
rule-props (or (:props production) {})]
{:env rule-env
:name rule-name
:props rule-props
:bindings bindings}))
22 changes: 20 additions & 2 deletions src/main/clojure/clara/rules/compiler.clj
Original file line number Diff line number Diff line change
Expand Up @@ -2127,12 +2127,30 @@

(defn add-production-load-order
"Adds ::rule-load-order to metadata of productions. Custom DSL's may need to use this if
creating a session in Clojure without calling mk-session below."
creating a session in Clojure without calling mk-session below.
Use add-production-load-data if you also want to merge default props."
[productions]
(map (fn [n production]
(vary-meta production assoc ::rule-load-order (or n 0)))
(range) productions))

(defn add-production-load-data
"Adds ::rule-load-order to metadata of productions, and merges default props.
Custom DSL's may need to use this if creating a session in Clojure without calling mk-session below."
[productions {:keys [default-props]}]
(let [merge-with-default-props (partial merge default-props)
maybe-merge-default-props (if (and (map? default-props)
(not-empty default-props))
(fn do-merge
[production]
(update production :props merge-with-default-props))
identity)]
(map (fn [n production]
(-> production
(vary-meta assoc ::rule-load-order (or n 0))
(maybe-merge-default-props)))
(range) productions)))

(defn- classify-load-type
[source]
(cond
Expand Down Expand Up @@ -2177,7 +2195,7 @@
{:keys [productions
hierarchies]} (->> (mapcat load-source* sources)
(group-by classify-load-type))
productions-loaded (add-production-load-order productions)
productions-loaded (add-production-load-data productions options)
productions-unique (hs/set productions-loaded)
productions-sorted (with-meta
(into (sorted-set-by production-load-order-comp) productions-unique)
Expand Down
Loading
Loading