This package provides a persistent cache mechanism for `load-path'
lookups to speed up Emacs startup and library loading.

It leverages the `load-path-filter-function' variable introduced in
Emacs 31.  By caching the directory locations of loaded libraries to
a file, it reduces the number of system calls (stat/access) required
when `require' or `load' is called, particularly beneficial for
systems with slow I/O or large `load-path' lists.

To use this package, add the following to your init file:

  (require 'persistent-cached-load-filter)
  (persistent-cached-load-filter-easy-setup)

Which is equivalent to:

  (require 'persistent-cached-load-filter)
  (when (boundp 'load-path-filter-function)
    (setq load-path-filter-function #'persistent-cached-load-filter)
    (add-hook 'kill-emacs-hook #'persistent-cached-load-filter-write-cache))

To cache as many path lookups as possible, it is recommended to
place the configuration code as early as possible in your init file.
You can use the following form to prevent errors if the package is
not yet installed:

  (when (require 'persistent-cached-load-filter nil t)
    (persistent-cached-load-filter-easy-setup))

The cache is automatically saved to `load-path-cache.eld' in your
`user-emacs-directory' when Emacs exits.

To write cache to file manually, use `persistent-cached-load-filter-write-cache'.
To clear cache, use `persistent-cached-load-filter-clear-cache'.

NOTE ON BENCHMARKING:

You can change `persistent-cached-load-filter-assoc-type' to
benchmark different data structures.  Note that if you change the
type, you MUST clear the existing cache file before restarting Emacs,
as the disk format changes depending on the chosen type.

TODO:

* The current implementation shadows packages with the same name
  appearing later in the load-path (similar to standard Emacs
  behavior).  Future versions might explore improvements to this
  logic.  Use `list-load-path-shadows' to check shadowed packages.