|IDL Reference Guide: Procedures and Functions|
The PATH_CACHE procedure is used to control IDL's use of the path cache. By default, as IDL searches directories included in the !PATH system variable for
.sav files to compile, it creates an in-memory list of all
.sav files contained in each directory. When IDL later searches for a
.sav file, before attempting to open the file in a given directory, IDL checks the path cache to determine whether the directory has already been cached. If the directory is included in the cache, IDL uses the cached information to determine whether the file will be found in that directory, and will only attempt to open the file there if the cache tells it that the file exists. By eliminating unnecessary attempts to open files, the path cache speeds the path searching process.
The path cache is enabled by default, and in almost all cases its operation is transparent to the IDL user, save for the boost in path searching speed it provides. Because the cache automatically adjusts to changes made to IDL's path, use of PATH_CACHE should not be necessary in typical IDL operation. It is provided to allow complete control over the details of how and when the caching operation is performed.
Prior to IDL 6.0, IDL did not use a path cache. Aside from the improvement in performance, the behavior of IDL with the path cache is identical to that without in almost all cases. The rare cases in which it differs, and options for disabling its use, are discussed in Options for Avoiding Use of the Path Cache.
The first time an IDL session attempts to call a function or procedure written in the IDL language, it must locate and compile the file containing the code for that routine. The file containing the routine must have the same name as the routine, with either a
.pro or a
.sav extension. After trying to open the file in the user's current working directory, IDL will attempt to open the file in each of the directories listed in the !PATH system variable, in the order specified by !PATH. The search stops when a file with the desired name is found or no directories remain in !PATH.
By default, IDL maintains an in-memory cache of the locations of
.sav files stored in directories included in the !PATH system variable. The path cache is built automatically during normal operation, as IDL searches the directories specified by !PATH. Once a directory is cached, IDL knows whether or not it contains a given file, without the need to actually attempt to open that file. This information allows IDL to bypass directories that do not contain the desired file, providing a significant boost in the speed of path searching. The path cache can significantly improve the startup speed of large, object-oriented applications, because method resolution requires extensive path searching.
The path cache operates on a per-directory basis; if IDL searches a directory for a
.sav file, the locations of all
.sav files in that directory are added to the cache, and the directory is not searched again until the cache is cleared and rebuilt.
The current contents of the path cache can be viewed using the PATH_CACHE keyword to the HELP procedure.
PATH_CACHE[, /CLEAR] [, /ENABLE] [, /REBUILD]
Set this keyword to clear the entire contents of the path cache, leaving it completely empty. If path caching is enabled, IDL will begin rebuilding the cache the next time it needs to locate a
.sav file. If you wish to prevent the rebuilding of the cache, set the ENABLE keyword equal to zero as well.
The .RESET_SESSION executive command clears the entire path cache as part of resetting the IDL session.
Set this keyword to a non-zero value to specify that IDL should use the path cache when searching for files and also add new directories to the cache as they are opened. Set this keyword to zero to disable use of the cache when searching for files, and to discontinue adding new directories.
Disabling the cache does not cause the current contents of the cache to be discarded. To discard the cache information, specify the CLEAR keyword.
Set this keyword to discard the current contents of the path cache (as if the CLEAR keyword had been specified), and then immediately rebuild the cache by searching the directories specified by the current value of the !PATH system variable for
If !PATH contains many directories, or if access to those directories is slow, rebuilding the cache using this method may also be slow. In many cases, the CLEAR keyword is sufficient, since IDL will rebuild the empty cache as program execution requires it to search for
By default, IDL uses the path cache whenever it tries to locate
.sav files. However, IDL will never use the path cache in the following situations:
The path cache is neither checked nor added to if the file being searched for exists in the current working directory. Before IDL searches !PATH for a file to compile, it always looks in the current working directory without checking the cache.
The path cache does not cache directories specified relative to the current directory, even though relative paths are allowed in the specification of !PATH.
An absolute (or fully qualified) path is a path that completely specifies the location of a file. Under UNIX, an absolute path is specified relative to the root of the filesystem, and therefore starts with a slash (
/) character. Under Microsoft Windows, an absolute path starts with a drive letter (
C:, for example) or a double backslash (
\\) (if the file is specified using the Universal Naming Convention format). In contrast, a relative path is incomplete, and must be interpreted relative to the current working directory of the IDL process. IDL only caches absolute paths.
The path cache is neither checked nor added to when a
.RUN executive command is issued. In such cases, IDL performs a standard directory-by-directory search of the directories included in !PATH.
IDL will not cache the contents of any directory that contains a file named
IDL_NOCACHE. See Marking Specific Directories as Uncacheable for additional information on this feature.
IDL will neither check nor add files to the path cache if it has been disabled. See Disabling the Path Cache, below, for additional information.
By default, IDL caches the locations of
.sav files in all directories specified by the !PATH system variable. Use of the path cache can be fully disabled in the following ways:
In addition, you can selectively disable use of the path cache for specific directories by creating a file named
IDL_NOCACHE in the directory. See Marking Specific Directories as Uncacheable for details.
You can mark specific directories as being uncacheable even though the directory is included in !PATH. To do so, create a file named
IDL_NOCACHE in that directory.
IDL does not inspect the contents of an
When IDL encounters a directory containing an
IDL_NOCACHE file during normal path searching, it makes a special entry in the path cache telling it that the directory must not be cached. Once this is done, all future attempts to locate files in that directory will be done without using cached information.
If the directory to which you add an
To re-enable path caching for a directory that has been marked as uncacheable, remove the
IDL_NOCACHE file, and then reset IDL's path cache in one of the following ways:
In most cases, the files contained in directories included in !PATH do not change during an IDL session. In such cases the path cache is completely transparent to the IDL user, and serves only to speed compilation of IDL routines. As a result, there is rarely a reason to globally disable the path cache.
If files are created or deleted in a directory included in !PATH during an IDL session, the path cache can become confused and provide bad information to IDL about the contents of that directory. There are several ways to handle this situation. The following list of alternatives is given in rough order of preference, with the easiest and lowest-impact options given first:
IDL_NOCACHEfile, as described in Marking Specific Directories as Uncacheable. This approach works for all IDL sessions that access the directory, and is therefore convenient in long-term or multi-user situations.
Depending on the value of your !PATH system variable, you may notice that some directories are being cached immediately when IDL starts up. This will occur if your path definition string includes the
<IDL_DEFAULT> token, or if one or more entries include the "+" symbol. In these cases, in order for IDL to build the !PATH system variable, it must inspect subdirectories of the specified directories for the presence of
.sav files, with the side effect of adding these directories to the path cache. See EXPAND_PATH for a discussion of IDL's path expansion behavior.
The following statement disables path caching for the current session:
PATH_CACHE, ENABLE = 0
The following statement disables path caching for the current session and throws away the current contents of the cache:
PATH_CACHE, ENABLE = 0, /CLEAR
Suppose you want to remove a directory included in !PATH from the cache without resetting your IDL session. The following statements cause the specified directory not to be included in future caching by creating a file named
IDL_NOCACHE in that directory:
OPENW, UNIT = u, '/home/idluser/idl_dev_dir/IDL_NOCACHE', /GET_LUN FREE_LUN, u
The OPENW and FREE_LUN statements create an empty file with the desired name in the target directory. Executing the following statement clears the cache so as to reflect the change in the current IDL session:
The next time IDL encounters this directory in a path search, it will see the presence of the
IDL_NOCACHE and make a note in the path cache that the directory is not cacheable.
You can also create the
.FULL_RESET_SESSION, .RESET_SESSION, !PATH, Environment Variables Used by IDL, Path Preferences
IDL Online Help (March 06, 2007)