Working with the Rules Assembly cache

When a requestor needs to execute an activity (or another rule that Process Commander assembles into Java upon first use) that is already compiled, the system loads the compiled code from disk (if necessary) and executes it promptly.

However, when there is no such compiled version (reflecting the user's current node and RuleSet list), the system must generate, compile, and save the Java code before it can execute it.

In a production setting where rules change rarely and the same rules are executed repeatedly, the rules cache can have a high hit rate with few rules needing to be assembled and compiled on first use. In a lightly used system with many developers, frequent rule changes, and many rules checked out, the hit rate is likely to be lower, and significant system resources will be used.

Each entry in the rule assembly cache is represented by an instance of the Java class FUAEntry. By default, the rules assembly cache contains up to 20,000 entries, speeding access to the Java CLASS files. Though rarely needed, you can change this limit with a prconfig.xml setting:

<env name="fua/global/instancecountlimit" value="nnnnn" />

Use the System Management Application to determine the current rule count and size in bytes of the Rules Assembly cache.

1. From the Developer portal, start the System Management Application using Tools > System Management Application. You may be prompted for a username and password.
2. Select a node.
3. Click Memory Management from the SMA left menu strip. In the right panel, locate the table row labeled Rule Assembly in the Caches group.

During normal system operations, each newly assembled rule is recorded as an additional entry in the cache. For each entry, the system records a use count (since startup), how many times the CLASS was loaded, and the date and time of the last use.

The system removes entries from the cache when a newer assembly compilation of the rule is required because the rule or another rule it depends on was modified.

Because of Java code inlining, one cache entry may support a few different actual rules, so the number of cache items may be lower than the actual number of rules that can be satisfied through the cache.

If the cache becomes full, the system purges entries with a low-use count to make room for additional entries.

When you update (or create or delete) a rule, it may "invalidate" one or more other rules present in the cache. A PEGA0032 alert occurs if updating a single rule invalidated more than 10 other rules, bringing your attention to a situation that can hurt performance by causing additional rules assembly. You can change this threshold.

Once each day, the Pega-RULES agent records a snapshot of the contents of the rules assembly cache, saving information into instances of the Log-RuleUsage and Log-RuleUsage-Details classes. (In the schema for the PegaRULES database, instances of these classes are saved as rows of the pr4_log_rule_usage and pr4_log_rule_usage_details tables, respectively.)

At the next startup, the system uses this snapshot information from the most recent day to reconstruct parts of the rules assembly cache. This process increases startup time but can provide a performance benefit by avoiding the need to reassemble and recompile rules that are already assembled and compiled from earlier system sessions.

When a Process Commander server node shuts down (intentionally or unintentionally), the in-memory portion of the rule assembly cache is lost; the Java class files remain on the disk. To avoid having to reassemble all the cache entries, regenerate the Java code, and recompile it (as though the rules had never been executed), Process Commander uses the Java class files to recreate a portion of the most heavily used cache entries. This capability is especially useful during peak load periods when resource demands are at their greatest.

When a server is restarted, the system:

1. Gathers usage statistics from the most recent snapshot in the Log-RuleUsage class for the node being restarted.
2. Creates a list of rules that have changed since the snapshot to eliminate Java classes whose input rules may have changed.
3. Calculates the maximum number of Java classes to reload based on the value set in instancecountlimit, loads unchanged Java class from disk based on the usage statistics, and finds instances from Log-RuleUsage-Details.
4. Creates new FUAEntry instances in the cache using each discovered detail row, up to 10% of the cache size (so by default up to 2000 entries are added during the startup-priming).
5. Rebuilds cache entries that were not recreated (changed after the snapshot, for instance). Each of the new entries is qualified by the user's RuleSet list and server node. For example, if user A has executed and cached a rule in her RuleSet list, and User B has executed the same rule but changed it after the snapshot, the rule in User B's list must be reassembled and re-cached when it is executed.

If the latest snapshot is more than 48 hours old, it is not considered a valid basis for cache-priming, and cache priming does not occur.

This cache-priming capability is enabled by default. If necessary, you can disable it by following these steps:

1. Update the prconfig.xml file to contain the line:

<env name="fua/enablereload" value="false" />

2. Stop and restart or redeploy the system.

When disabled, the system creates new cache entries when a user calls a rule (reflecting the user's current node and RuleSet list), which generates, compiles, and saves the Java code before executing it.

Typically, rules assembly processing occurs less often in a production system or in a system that has heavy use, because most of the time, users execute rules that are already assembled and compiled. However, in certain situations, even when rules change rarely, excessive rules assembly processing can affect overall system performance. To encourage greater reuse and sharing of already-assembled rules:

• Minimize the number of distinct access groups and application rules in use
• Disable rule check-out for users who do not need this capability
• Tune the rules assembly cache, ensuring that it is big enough so that assembled rules are not "bumped".