C# Class GSF.IO.CachedFileStream

Represents a file stream that caches recently used blocks in memory.

This class was developed as a wrapper around System.IO.FileStream with the same basic functionality. This stream treats the file as a collection of contiguous blocks which can be loaded into an in-memory lookup table to greatly improve seek times. This class generally performs significantly better than the standard FileStream class when maintaining multiple file pointers and frequently seeking back and forth between them. For an example of a good use-case, consider copying a list of serialized objects from one location in the file to another without loading the whole list into memory.

This class likely will not perform significantly better or worse than the standard FileStream when performing strictly sequential reads or writes. For an example of a bad use-case, consider reading a list of objects into memory or simply appending new data to the end of the file. In both of these cases, it may be better to use the standard FileStream for less memory overhead and more predictable flush behavior.

Blocks are loaded into memory as they are used (for read/write operations) and will be kept in memory for as long as possible. Blocks can only be flushed from the cache by decreasing the cache size or by accessing a non-cached block when the cache is already full. In these cases, a least recently used algorithm is executed to determine which blocks should be removed from the cache either to decrease the size of the cache or to make room for a new block.

Write operations are also cached such that they will not be committed to the file until the block is removed from the cache or a call to Flush() has been made. This can have some additional implications as compared to the standard FileStream. For instance, write operations may not be committed to the file in the order in which they were executed. Users of this class will need to be judicious about when and how often they call Flush.

Inheritance: Stream
Show file Open project: GridProtectionAlliance/gsf

Public Methods

Method Description
CachedFileStream ( string path, FileMode mode ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileAccess access ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize, FileOptions options ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize, bool useAsync ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileSystemRights rights, FileShare share, int blockSize, FileOptions options ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, access rights and sharing permission, the buffer size, and additional file options.
CachedFileStream ( string path, FileMode mode, FileSystemRights rights, FileShare share, int blockSize, FileOptions options, FileSecurity fileSecurity ) : System

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, access rights and sharing permission, the buffer size, additional file options, access control and audit security.
Flush ( ) : void

Clears buffers for this stream and causes any buffered data to be written to the file.
Flush ( bool flushToDisk ) : void

Clears buffers for this stream and causes any buffered data to be written to the file, and also clears all intermediate file buffers.
Read ( byte buffer, int offset, int count ) : int

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
Seek ( long offset, SeekOrigin origin ) : long

When overridden in a derived class, sets the position within the current stream.
SetLength ( long value ) : void

When overridden in a derived class, sets the length of the current stream.
Write ( byte buffer, int offset, int count ) : void

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

Protected Methods

Method Description
Dispose ( bool disposing ) : void

Releases the unmanaged resources used by the T:System.IO.Stream and optionally releases the managed resources.

Private Methods

Method Description
AddRef ( Block block ) : void
CachedFileStream ( int blockSize ) : System
CleanQueue ( ) : void
GetBlock ( long blockIndex ) : Block
PurgeCache ( long cacheSize ) : void
RemoveRef ( Block block ) : void
WriteToFileStream ( Block block ) : void

Method Details

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. contains an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The requested is not permitted by the operating system for the specified , such as when is Write or ReadWrite and the file or directory is set for read-only access. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileAccess access ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
access FileAccess A constant that determines how the file can be accessed by the FileStream object. This gets the and properties of the FileStream object. is true if specifies a disk file.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. , , or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The requested is not permitted by the operating system for the specified , such as when is Write or ReadWrite and the file or directory is set for read-only access. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
access FileAccess A constant that determines how the file can be accessed by the FileStream object. This gets the and properties of the FileStream object. is true if specifies a disk file.
share FileShare A constant that determines how the file will be shared by processes.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. is negative or zero.-or- , , or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The requested is not permitted by the operating system for the specified , such as when is Write or ReadWrite and the file or directory is set for read-only access. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
access FileAccess A constant that determines how the file can be accessed by the FileStream object. This gets the and properties of the FileStream object. is true if specifies a disk file.
share FileShare A constant that determines how the file will be shared by processes.
blockSize int A positive value greater than 0 indicating the block size. For values between one and eight, the actual block size is set to eight bytes.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. is negative or zero.-or- , , or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The requested is not permitted by the operating system for the specified , such as when is Write or ReadWrite and the file or directory is set for read-only access. -or- is specified for , but file encryption is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize, FileOptions options ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
access FileAccess A constant that determines how the file can be accessed by the FileStream object. This gets the and properties of the FileStream object. is true if specifies a disk file.
share FileShare A constant that determines how the file will be shared by processes.
blockSize int A positive value greater than 0 indicating the block size. For values between one and eight, the actual block size is set to eight bytes.
options FileOptions A value that specifies additional file options.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. is negative or zero.-or- , , or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred.-or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The requested is not permitted by the operating system for the specified , such as when is Write or ReadWrite and the file or directory is set for read-only access. The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileAccess access, FileShare share, int blockSize, bool useAsync ) : System
path string A relative or absolute path for the file that the current FileStream object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
access FileAccess A constant that determines how the file can be accessed by the FileStream object. This gets the and properties of the FileStream object. is true if specifies a disk file.
share FileShare A constant that determines how the file will be shared by processes.
blockSize int A positive value greater than 0 indicating the block size. For values between one and eight, the actual block size is set to eight bytes.
useAsync bool Specifies whether to use asynchronous I/O or synchronous I/O. However, note that the underlying operating system might not support asynchronous I/O, so when specifying true, the handle might be opened synchronously depending on the platform. When opened asynchronously, the and methods perform better on large reads or writes, but they might be much slower for small reads or writes. If the application is designed to take advantage of asynchronous I/O, set the parameter to true. Using asynchronous I/O correctly can speed up applications by as much as a factor of 10, but using it without redesigning the application for asynchronous I/O can decrease performance by as much as a factor of 10.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, access rights and sharing permission, the buffer size, and additional file options.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. is negative or zero.-or- , access, or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. The current operating system is not Windows NT or later. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred. -or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The access requested is not permitted by the operating system for the specified , such as when access is Write or ReadWrite and the file or directory is set for read-only access. -or- is specified for , but file encryption is not supported on the current platform. The specified , file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
public CachedFileStream ( string path, FileMode mode, FileSystemRights rights, FileShare share, int blockSize, FileOptions options ) : System
path string A relative or absolute path for the file that the current object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
rights FileSystemRights A constant that determines the access rights to use when creating access and audit rules for the file.
share FileShare A constant that determines how the file will be shared by processes.
blockSize int A positive value greater than 0 indicating the block size. For values between one and eight, the actual block size is set to eight bytes.
options FileOptions A constant that specifies additional file options.
return System

CachedFileStream() public method

Initializes a new instance of the T:System.IO.FileStream class with the specified path, creation mode, access rights and sharing permission, the buffer size, additional file options, access control and audit security.
is null. is an empty string (""), contains only white space, or contains one or more invalid characters. -or- refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. is negative or zero.-or- , access, or contain an invalid value. The file cannot be found, such as when is FileMode.Truncate or FileMode.Open, and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying FileMode.CreateNew when the file specified by already exists, occurred. -or-The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. The access requested is not permitted by the operating system for the specified , such as when access is Write or ReadWrite and the file or directory is set for read-only access. -or- is specified for , but file encryption is not supported on the current platform. The specified , file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters. The current operating system is not Windows NT or later.
public CachedFileStream ( string path, FileMode mode, FileSystemRights rights, FileShare share, int blockSize, FileOptions options, FileSecurity fileSecurity ) : System
path string A relative or absolute path for the file that the current object will encapsulate.
mode FileMode A constant that determines how to open or create the file.
rights FileSystemRights A constant that determines the access rights to use when creating access and audit rules for the file.
share FileShare A constant that determines how the file will be shared by processes.
blockSize int A positive value greater than 0 indicating the block size. For values between one and eight, the actual block size is set to eight bytes.
options FileOptions A constant that specifies additional file options.
fileSecurity FileSecurity A constant that determines the access control and audit security for the file.
return System

Dispose() protected method

Releases the unmanaged resources used by the T:System.IO.Stream and optionally releases the managed resources.
protected Dispose ( bool disposing ) : void
disposing bool true to release both managed and unmanaged resources; false to release only unmanaged resources.
return void

Flush() public method

Clears buffers for this stream and causes any buffered data to be written to the file.
An I/O error occurs.
public Flush ( ) : void
return void

Flush() public method

Clears buffers for this stream and causes any buffered data to be written to the file, and also clears all intermediate file buffers.
An I/O error occurs.
public Flush ( bool flushToDisk ) : void
flushToDisk bool true to flush all intermediate file buffers; otherwise, false.
return void

Read() public method

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
and describe an invalid range in . is null. or is negative. An I/O error occurs. The stream does not support reading. Methods were called after the stream was closed.
public Read ( byte buffer, int offset, int count ) : int
buffer byte An array of bytes. When this method returns, the buffer contains the specified byte array with the values between and ( + - 1) replaced by the bytes read from the current source.
offset int The zero-based byte offset in at which to begin storing the data read from the current stream.
count int The maximum number of bytes to be read from the current stream.
return int

Seek() public method

When overridden in a derived class, sets the position within the current stream.
Methods were called after the stream was closed.
public Seek ( long offset, SeekOrigin origin ) : long
offset long A byte offset relative to the parameter.
origin SeekOrigin A value of type indicating the reference point used to obtain the new position.
return long

SetLength() public method

When overridden in a derived class, sets the length of the current stream.
Attempted to set the parameter to less than 0. An I/O error occurs. The stream does not support both writing and seeking. Methods were called after the stream was closed.
public SetLength ( long value ) : void
value long The desired length of the current stream in bytes.
return void

Write() public method

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.
and describe an invalid range in . is null. or is negative. An I/O error occurs. The stream does not support writing. Methods were called after the stream was closed.
public Write ( byte buffer, int offset, int count ) : void
buffer byte An array of bytes. This method copies bytes from to the current stream.
offset int The zero-based byte offset in at which to begin copying bytes to the current stream.
count int The number of bytes to be written to the current stream.
return void