Implements a caching mechanism for file and directory state information.

lazfilecache.pas implement a caching mechanism used for file and directory state information. It is used in the implementation of the Lazarus IDE, and in the LCL package system.

This file is part of the LazUtils package.

Represents flag values used for files or directories in the state caching mechanism.

TFileStateCacheItemFlag is an enumerated type with values that represent flags used for files or directories in the state caching mechanism. Values from the enumeration are stored in the TFileStateCacheItemFlags set type, and used in the implementation of the TFileStateCacheItem class.

File or directory exists. File exists and is a directory. File is readable. File is writable. File is a directory and can be searched. File is a directory and allows new files to be created. File is a text (not an executable binary) file. File is an executable binary file. file age is valid. Physical file name for the file is valid. Set type used to store TFileStateCacheItemFlag enumeration values. Contains information about a file or directory in the state caching mechanism.

TFileStateCacheItem is a class which contains information about a file or directory in the state caching mechanism. TFileStateCacheItem has properties used to represent a file or directory name (symbolic and physical), a timestamp, and status flags.

TFileStateCacheItem is the type creates and stored in the internal AVL tree in TFileStateCache using its FindFile method.

Constructor for the class instance.

Create is the constructor for the class instance. It sets the initial values for the following properties:

Filename: Set to the value passed in TheFilename.
TimeStamp: Set to the value passed in NewTimeStamp.

Name for the file or directory in the cache item. Timestamp value for the file or directory. Gets the memory size needed to store the class instance. TObject.InstanceSize Number of bytes needed to store the class instance and its assigned data. Name for the file or directory in the cache item. Physical name for the file or directory in the cache item. Contains status flags for the cached file or directory item. Contains status flags that have been tested for the cached item. Timestamp for the cached item.

Timestamp is an Int64 property with a timestamp value for an item in the state caching mechanism. It is not actually a time value; it is a counter that is assigned when the item is added to the TFileStateCache class. It can be compared to the Timestamp value in the state cache to determine when the item is potentially out-of-date.

Use TFileStateCache.Timestamp to determine when the cached item is invalid.

FileAge value for the file or directory.

Age is a LongInt property with the file age for the file or directory in the cache item. The value for the property is assigned when the TFileStateCache.FileAgeCached method is called, and contains the value returned from the FileAge routine in SysUtils.

FileAge Specifies an event handler signalled when the timestamp for a cached item is changed. Object instance for the event notification. Name for the affected file or directory. Implements a state caching mechanism for files and directories.

TFileStateCache is a class which implements a state caching mechanism for files and directories. TFileStateCache uses an internal AVL tree to store TFileStateCacheItem instances for the items in the state caching mechanism. The tree stores values sorted in file name (or path) order.

The TimeStamp property contains a counter value, assigned in the constructor, which is maintained when items are added or updated in cache storage. The value is assigned to cached items, and provides an indication when the cached item may be out-of-date in the cache.

TFileStateCache provides methods to add and update items in the cache, and to access and verify state flags for the TFileStateCacheItem instances.

Includes or excludes a value in the Flags property. File or directory name for the cached item. Identifies the Flag affected in the method. True to include the flag, False to exclude it. Constructor for the class instance.

Create is the constructor for the class instance. It allocates resources needed for the internal AVL tree used to store the file or directory items in the cache mechanism. The address for the CompareFileStateItems routine is used to compare and sort the items added to the AVL tree. It also sets the initial value in the Timestamp property.

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It frees resources allocated in and for the internal AVL tree used to store cached file or directories. It also frees any change handler routines assigned by calling the AddChangeTimeStampHandler method.

Destroy calls the inherited method prior to exit.

Increments the lock count for the caching mechanism. Decrements the lock count for the caching mechanism.

Raises an Exception if the lock count is 0 (or less) when the method is called.

Indicates Lock has been called without a corresponding Unlock call. The return value is True when the internal lock count has a positive non-zero value. True when the internal lock count has a positive non-zero value. Increments the change counter or updates an item in the state cache.

AFileName contains the file or directory name to update in the storage for the cache.

When AFileName is an empty string (''), the entire cache is invalidated by incrementing the change counter in the TimeStamp property. If a value is provided in AFileName, a single item is invalidated in the cache storage. The FindFile method is called to retrieve the TFileStateCacheItem entry and to reset the values in its TestedFlags property.

IncreaseTimeStamp signals each of the assigned change handlers for the class instance using the value in AFileName as an argument.

Name for the file or directory invalidated in the cache, or an empty string to invalidate all cached items. Ensures that a cached item has an up-to-date "file exists" flag value.

FileExistsCached ensures that a cached item with the name in AFileName has an up-to-date "file exists" flag value in the cache.

Calls Check to use the valid flag value for an existing TFileStateCacheItem instance in the cache. If the return value from Check is True, no additional actions are performed in the method.

Otherwise, the flag value was not present for the specified cache item. The FileExistsUTF8 routine is called to determine if the file exists on the local file system. SetFlag is called to update the fsciExists flag for the cache item with the given name.

True if the file exists on the local file system and in the cache. Name for the file to examine in the method. Ensures that a cached item has an up-to-date "directory path exists" flag value.

DirPathExistsCached ensures that a cached item with the name in AFileName has an up-to-date "directory path exists" flag value in the cache.

Calls Check to use the valid flag value for an existing TFileStateCacheItem instance in the cache. If the return value from Check is True, no additional actions are performed in the method.

Otherwise, the flag value was not present for the specified cache item. The DirPathExists routine is called to determine if the file exists on the local file system. SetFlag is called to update the fsciDirectory flag for the cache item with the given name.

True if the directory exists on the local file system and in the cache. Name of the directory to examine in the method. Ensures that a cached item has an up-to-date "Directory is Writable" flag.

DirectoryIsWritableCached ensures that the specified directory has an up-to-date value for its "Directory is Writable" flag in the cache. It calls Check to use a valid flag value for an existing TFileStateCacheItem instance in the cache. If the return value from Check is True, no additional actions are performed in the method.

Otherwise, the flag value was not present for the specified cache item. The DirectoryIsWritable routine is called to determine if the directory allows new entries to be created in the path. SetFlag is called to update the fsciDirectoryWritable flag for the cache item with the given name.

True if the specified directory is writable in the local file system and in the cache. Name of the directory to examine in the method. Ensures that the "File is Executable" flag is up-to-date for a cache item.

FileIsExecutableCached ensures that the cache item for the specified file has an up-to-date value in its "File is Executable" flag. It calls Check to get the cache item with the given name, and to examine its flag values. If Check returns True for the flag, no additional actions are performed in the method.

Otherwise, the FileIsExecutable routine is called to get the return value. SetFlag is called to apply the fsciExecutable flag value to the cached item.

FileIsExecutable True if the specified file is an executable binary. Name for the file examined in the method. Ensures that the "File is Readable" flag is up-to-date for a cache item. True if the specified file is not read-only. Name for the file examined in the method. Ensures that the "File is Writable" flag is up-to-date for a cache item. True if the file is writable. Name for the file examined in the method. Ensures that the "File is Text" flag is up-to-date for a cache item. True if the file is a text file (not a binary executable). Name for the file examined in the method. Ensures that the file age is up-to-date for a cache item.

FileAgeCached differs from the related methods in the class instance. It returns a LongInt value instead of a Boolean, and contains the value from the FileAge routine in the RTL SysUtils unit. The value represents the last date that the file was modified, and the integer value does not include any time-related information for the modification timestamp.

FileAgeCached cannot be used for directory names; the value is always -1 when used for a directory name.

FileAge is not related to the TimeStamp property for the cache.

FileAge File age (last modification date) for the file. Name for the file examined in the method. Gets (or creates) the cached item with the specified name.

FindFile is a TFileStateCacheItem function used to get, or optionally create, a cache entry for the file or directory in Filename.

FindFile resolves a relative path used in Filename by calling the ResolveDots routine. The normalized name is used to get the TFileStateCacheItem instance in the cache used as the return value for the method.

If Filename was not found in the cache, and CreateIfNotExists is set to True, a TFileStateCacheItem instance is created with the Timestamp for the cache and added to the internal storage. An Exception is raised if the cache item could not be added (and retrieved) using the internal AVL tree storage.

If Filename was not found in the cache, and CreateIfNotExists is set to False, the return value is Nil.

FindFile is used to implement the Check and IncreaseTimeStamp methods.

Cached item with the specified name, or Nil. Name for the file or directory to locate in the cache. True to create a cache item if it does not already exist. Checks the specified cache item to get a specific flag value.

Check is a Boolean function used to check a flag value in a cache item with the name in Filename.

AFlag identifies the flag value checked for the cache item.

AFile contains the cache item used to get the value for the specified flag. The FindFile method is called to get (or create) a cache item for the specified file or directory name. AFile is an output parameter, and is used to return the TFileStateCacheItem instance to the caller.

Check ensures that the cache item is valid (recent) using the Timestamp for the class instance. When TimeStamp is more recent than the value in the cache item, the cache item is updated with the current Timestamp and its tested flags are cleared.

FlagIsSet is a variable parameter which contains the state for the specific flag. True indicates the flag is set for the cache item. False indicates that the flag was not already set in the cache item, or has not been tested after resetting the Timestamp for an invalid cache item.

The return value is True when the flag in AFlag is one of the tested flags in an existing cache item. It is False if the flag value has not been accessed in the cache item, or when the Timestamp for an invalid cache item was reset.

Check is used to implement methods which get or set specific flag values, including:

FileExistsCached
DirPathExistsCached
DirectoryIsWritableCached
FileIsExecutableCached
FileIsReadableCached
FileIsWritableCached
FileIsTextCached
FileAgeCached
GetPhysicalFilenameCached

True if the flag is has been tested and set for the cache item. File or directory to locate in the cache. Flag to examine for the cache item. The cache item examined in the method. True if the flag was tested and set for the cache item. Adds the specified handler routine to the class instance. Handler routine added in the method. Removes the specified handler routine in the class instance. Handler routine removed in the method. Gets the memory size needed for the class instance and its data.

CalcMemSize is a name function used to get the amount of memory needed for the class instance, including data stored in its properties. The return value is a sum of the InstanceSize and the lengths for the String values in FileName and PhysicalFilename.

TObject.InstanceSize Memory size needed to store the class instance and its data. Timestamp (or revision) value for the cache storage. Unit global variable with the class instance for the state caching mechanism.

FileStateCache is a FileStateCache variable which contains the class instance used for the state caching mechanism. The default value for the variable is Nil (unassigned).

Gets the File Exists flag value for the specified file name. True if the file exists on the local file system. File name examined in the routine. Gets the Path Exists flag value for the specified directory path. True if the path exists on the local file system. Path to the directory examined in the routine. Gets the Directory is Writable flag value for the specified path. True if the specified directory allows files or sub-directories to be created. Path examined in the routine. Gets the File is Executable flag value for the specified file name. True if the specified file is an executable (binary) file. Name for the file examined in the routine. Gets the File is Readable flag value for the specified file name. True if the specified file is readable. Name for the file examined in the routine. Gets the File is Writable flag value for the specified file name. True if the specified file is writable (not read-only). Name for the file examined in the routine. Gets the File is Text flag for the specified file name. True if the specified file is a text (not a binary executable) file. Name for the file examined in the routine. Gets the file age for the specified file or directory. File age for the specified file or directory. File or directory name examined in the routine. Gets the physical file name for the specified file or directory name.

GetPhysicalFilenameCached is a String function used to get the physical file name for the value specified in AFileName. The return value contains the actual file name for a symbolic link or reference on the local file system.

EmptyOnError indicates that the return value can be an empty string ('') if AFilename cannot be resolved. When set to False, the original file in AFileName is used as the return value.

GetPhysicalFilenameCached provides two (2) ways to resolve the value in AFilename:

Calling the GetPhysicalFilenameCached method in the FileStateCache singleton (when assigned). This is the default code path in the routine.
Calling the GetPhysicalFilename routine.

Actual file name for the symbolic link or reference. File name resolved in the routine. True to return an empty string if AFilename is not found. Invalidates one or more items in the state cache.

Calls the IncreaseTimeStamp method in FileStateCache using the value in FileName as the target. When FileName exists in the cache, it is the only item affected in the method. If FileName is an empty string (''), all items in the cache are invalidated.

Name for the file or directory invalidated in the cache. TODO TODO Integer value used as the invalid timestamp value for the cache mechanism. Int64 value used as the invalid timestamp value for the cache mechanism. Increments the specified Integer timestamp value. Timestamp value modified in the routine. Increments the specified Int64 timestamp value. Timestamp value modified in the routine. Specifies an event handler signalled to get the "file exists" flag for an item in the cache. True if the file exists on the local file system. File name examined in the event handler. Specifies an event handler signalled to get the file age for an item in the cache. File age for the specified file or directory. File or directory examined in the handler. Event handler signalled to get the File Exists flag for the specified file name. Event handler signalled to get the file age for the specified file name.

OnFileAgeCached is a TOnFileAgeCached variable with the unit global event handler used to get the file age for a given file name. It is signalled from the FileAgeCached routine (when assigned), and is used instead of calling the TFileStateCache.FileAgeCached method or the FileAgeUTF8 routine in LazUtils.

FileAgeUTF8