Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

PATH_CACHE

Syntax | Arguments | Keywords | Examples | Version History | See Also

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 .pro or .sav files to compile, it creates an in-memory list of all .pro and .sav files contained in each directory. When IDL later searches for a .pro or .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.

Note
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.

About 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 .pro and .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 .pro or .sav file, the locations of all .pro and .sav files in that directory are added to the cache, and the directory is not searched again until the cache is cleared and rebuilt.

Note
The current contents of the path cache can be viewed using the PATH_CACHE keyword to the HELP procedure.

Syntax

PATH_CACHE[, /CLEAR] [, /ENABLE] [, /REBUILD]

Arguments

None.

Keywords

CLEAR

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 .pro or .sav file. If you wish to prevent the rebuilding of the cache, set the ENABLE keyword equal to zero as well.

Note
The .RESET_SESSION executive command clears the entire path cache as part of resetting the IDL session.

ENABLE

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.

Note
Disabling the cache does not cause the current contents of the cache to be discarded. To discard the cache information, specify the CLEAR keyword.

REBUILD

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 .pro and .sav files.

Note
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 .pro and .sav files.

Situations in which IDL will not use the Path Cache

By default, IDL uses the path cache whenever it tries to locate .pro or .sav files. However, IDL will never use the path cache in the following situations:

Current Working Directory

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.

Relative Paths

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.

Executive Commands

The path cache is neither checked nor added to when a .COMPILE or .RUN executive command is issued. In such cases, IDL performs a standard directory-by-directory search of the directories included in !PATH.

IDL_NOCACHE File Present

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.

Path Cache Disabled

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.

Disabling the Path Cache

By default, IDL caches the locations of .pro and .sav files in all directories specified by the !PATH system variable. Use of the path cache can be fully disabled in the following ways:

  1. By issuing the PATH_CACHE command with the ENABLE keyword set equal to zero. This will disable the path cache until you manually re-enable it, or for the duration of the current IDL session. See the description of the ENABLE keyword, above, for details.
  2. By unchecking the "Enable Path Caching" checkbox on the Path tab of the IDLDE Preferences dialog. See "Path Preferences" in Chapter 5 of the Using IDL manual for details.
  3. By defining an environment variable named IDL_PATH_CACHE_DISABLE before starting IDL. See "Environment Variables Used by IDL" in Chapter 1 of the Using IDL manual for details.

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, below, for details.

Marking Specific Directories as Uncacheable

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.

Note
IDL does not inspect the contents of an IDL_NOCACHE file; it can contain anything you wish, or nothing at all. Under Unix operating systems, the IDL_NOCACHE file must be named exactly as shown, using all uppercase characters in the name. Under Microsoft Windows, the characters can have any case, but RSI suggests you use upper case for consistency.

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.

Note
If the directory to which you add an IDL_NOCACHE file has already been added to the path cache for the current IDL session, you must clear the existing cache (using the CLEAR keyword to the PATH_CACHE procedure) before the no-cache setting will take effect.

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:

Options for Avoiding Use of the Path Cache

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:

  1. Leave the path cache enabled, and change your current working directory to the directory in which files are created or deleted. Since IDL checks the current working directory before checking the directories in !PATH, use of the path cache does not affect IDL's ability to find these files.
  2. If the addition or deletion of files in a directory included in !PATH is a rare occurrence, leave the path cache enabled and clear it in one of the following ways after the contents of the directory have changed:
    • Specify the CLEAR keyword to the PATH_CACHE procedure.
    • Issue the .RESET_SESSION executive command.
    • Exit and restart the IDL session.
  3. Leave the path cache enabled and use the .COMPILE or .RUN executive commands to force the compilation of any file, regardless of the contents of the path cache.
  4. If you have a directory (other than your current working directory) in which files are regularly added or deleted during the execution of IDL sessions, you can leave path caching enabled but explicitly disable caching of that specific directory by creating an IDL_NOCACHE file, 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.
  5. You can completely disable operation of the path cache using one of the methods described under Disabling the Path Cache. This is not recommended, because most directories are not dynamic, and completely disabling path caching sacrifices the performance advantages of caching directories whose contents are static.

Note on Behavior at Startup

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 .pro and .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.

Examples

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: 

PATH_CACHE, /CLEAR

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.

Note
You can also create the IDL_NOCACHE file outside IDL using any convenient command (text editor, Unix touch command, etc.). If the file is created outside IDL, only the PATH_CACHE, /CLEAR statement is necessary.

Version History

Introduced: 6.0

See Also

.FULL_RESET_SESSION, .RESET_SESSION, !PATH, Environment Variables Used by IDL, Path Preferences

Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]