Spectre cache Options

The Spectre command line cache sub-command displays and manipulates the cache files. It has the following syntax:

spectre cache [options]

For example:

spectre cache

Enter spectre cache -h to display the syntax and options as shown in the following table.

Spectre cache Sub-command Options

Option Description
--dataroot arg

Set the path to the DiveLine server dataroot.

For example:

spectre cache --dataroot c:\di\solution\dl-dataroot

Instead of using this option, you can set the DI_HOME environment variable. See Setting Environment Variables.

--dry-run

Use with --sweep, --max-age, --max-idle, or --max-size to describe what the command would do but without modifying the cache.

For example:

spectre cache --dry-run --sweep

--info

Print a histogram with information about the cache state (default).

For example:

spectre cache --info

spectre cache

--list

Print a tab-delimited table of the contents of the cache.

For example:

spectre cache --list

Columns in this output include ID, Last Access, Created, Updated, Access Count, Update Count, Size, and Initial User.

--list-advanced

Print a tab-delimited table of the contents of the cache including the request scripts and cache tokens.

For example:

spectre cache --list-advanced

Columns in this output include ID, Last Access, Created, Updated, Access Count, Update Count, Size, Initial User, Request, Token, and Milliseconds.

--max-age arg

Remove entries from the cache that have not been updated for this many hours.

For example:

spectre cache --max-age 12

Removes entries last updated over 12 hours ago.

--max-idle arg

Remove entries from the cache that have not been read for this many hours.

For example:

spectre cache --max-idle 6

Removes entries that have not been read in the last 6 hours.

--max-size arg

Remove the most idle entries until the entire cache is at most the specified size on disk in MB.

For example:

spectre cache --max-size 25

Removes idle entries one by one until the on-disk cache size is at most 25 MB.

--remove-all

Remove all cache entries.

For example:

spectre cache --remove all

Clears the cache.

--q [ --quiet ]

Print only warnings and errors to the console.

For example:

spectre cache --quiet --list

When the command runs with this option, no timestamps or individual processes display; only warnings and errors are output to the console. If successful, only the command prompt displays.

--sweep

Do a full scan for stale cache entries and remove them. A stale cache entry is one that is no longer valid because the source data has changed. For example:

spectre cache --sweep

This option removes the stale cache entries, which are not used for their data. However, stale entries can be useful for a refresh. This option also checks for and removes temporary cache entries that were unable to be moved into place.

--refresh

Refresh all stale cache entries. Refresh means to take a stale entry and re-run it to update the data. For example:

spectre cache --refresh

This is best used after a sequence of runs with the --max-age, --max-size, or --max-idle options. Run these options first, then --refresh all remaining entries. This option is also useful after rebuilding a cBase to ensure that cache entries are updated for the end users.

--refresh-with-predicate arg

Take an expression and evaluate it; if it is true, refresh the cache entries. This option is useful if the criteria are more complex.

The expression runs over a virtual table with the following columns:

  • "age": The number of hours since this cache entry was last updated
  • "idle": The number of hours since this cache entry was last read
  • "num_hits": The number of queries that were satisfied by reading this cache entry
  • "num_updated": The number of times this cache entry has been updated
  • "user": The current user name
  • "size": The size of this cache entry in bytes
  • "time_to_generate": The time to generate this cache in seconds

You can write expressions that refer to these columns. For example, if user Bob likes his queries cached but only if they took more than a second:

spectre cache --refresh-with-predicate "value(\"user\") = \"Bob\"

and value(\"time_to_generate\") > 1"

TIP: Doing a --sweep after a --refresh-with-predicate removes all the remaining stale entries, which use up disk space.

NOTE: Starting with Spectre 7.1(18), --refresh-with-predicate removes stale compiler cache entry (ccache requests) regardless of the predicate.

--remove-with-predicate arg

Take an expression and evaluate it; if it is true, remove the cache entries. This option is useful if the criteria are more complex.

The expression runs over a virtual table with the following columns:

  • "age": The number of hours since this cache entry was last updated
  • "idle": The number of hours since this cache entry was last read
  • "num_hits": The number of queries that were satisfied by reading this cache entry
  • "num_updated": The number of times this cache entry has been updated
  • "user": The current user name
  • "size": The size of this cache entry in bytes
  • "time_to_generate": The time to generate this cache in seconds

You can write expressions that refer to these columns. For example, if you know that cache entries over a certain size are really mistakes (for example, the initial dive was not a good one):

spectre cache --remove-with-predicate "value(\"size\") > 1024 * 1024 * 1024

and value(\"user\") != \"the boss\""

-j [ --jobs ] arg

With --refresh with predicate, specifies the maximum number of cache files to refresh in parallel.

spectre cache --refresh-with-predicate "value(\"age\") <= 36" -j 3

Up to 3 cache refreshes run in parallel. Use arg to set the number of core processors (likely between 2 and 8). Start with a lower number as this depends on the I/O capabilities of the host system.