Class FSDirectory

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Inheritance
object
Directory
BaseDirectory
FSDirectory
MMapDirectory
NIOFSDirectory
SimpleFSDirectory
Implements
Inherited Members
Namespace: Lucene.Net.Store
Assembly: Lucene.Net.dll
Syntax
public abstract class FSDirectory : BaseDirectory, IDisposable

Constructors

FSDirectory(DirectoryInfo)

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Declaration
protected FSDirectory(DirectoryInfo dir)
Parameters
Type Name Description
DirectoryInfo dir
See Also

FSDirectory(DirectoryInfo, LockFactory)

Create a new FSDirectory for the named location (ctor for subclasses).

Declaration
protected FSDirectory(DirectoryInfo path, LockFactory lockFactory)
Parameters
Type Name Description
DirectoryInfo path

the path of the directory
LockFactory lockFactory

the lock factory to use, or null for the default (NativeFSLockFactory);
Exceptions
Type Condition
IOException

if there is a low-level I/O error
See Also

Fields

DEFAULT_READ_CHUNK_SIZE

Default read chunk size: 8192 bytes (this is the size up to which the runtime does not allocate additional arrays while reading/writing)

Declaration
[Obsolete("this constant is no longer used since Lucene 4.5.")]
public const int DEFAULT_READ_CHUNK_SIZE = 8192
Field Value
Type Description
int
See Also

m_directory

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Declaration
protected readonly DirectoryInfo m_directory
Field Value
Type Description
DirectoryInfo
See Also

m_staleFiles

The collection of stale files that need to be Sync(ICollection<string>)'ed

Declaration
protected readonly ISet<string> m_staleFiles
Field Value
Type Description
ISet<string>
Remarks

LUCENENET NOTE: This is a non-thread-safe collection so that we can synchronize access to it using the m_syncLock field. This is to prevent race conditions, i.e. one thread adding a file to the collection while another thread is trying to sync the files, which could cause a missed sync. If you need to access this collection from a derived type, you should synchronize access to it using the protected m_syncLock field.

See Also

m_syncLock

A Monitor object to synchronize access to the m_staleFiles collection. You should synchronize access to m_staleFiles using this object from derived types.

Declaration
protected readonly object m_syncLock
Field Value
Type Description
object
See Also

Properties

Directory

the underlying filesystem directory

Declaration
public virtual DirectoryInfo Directory { get; }
Property Value
Type Description
DirectoryInfo
See Also

ReadChunkSize

this setting has no effect anymore.

Declaration
[Obsolete("this is no longer used since Lucene 4.5.")]
public int ReadChunkSize { get; set; }
Property Value
Type Description
int
See Also

Methods

CreateOutput(string, IOContext)

Creates an IndexOutput for the file with the given name.

Declaration
public override IndexOutput CreateOutput(string name, IOContext context)
Parameters
Type Name Description
string name
IOContext context
Returns
Type Description
IndexOutput
Overrides
See Also

DeleteFile(string)

Removes an existing file in the directory.

Declaration
public override void DeleteFile(string name)
Parameters
Type Name Description
string name
Overrides
See Also

Dispose(bool)

Closes the store to future operations.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing
Overrides
See Also

EnsureCanWrite(string)

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Declaration
protected virtual void EnsureCanWrite(string name)
Parameters
Type Name Description
string name
See Also

FileExists(string)

Returns true iff a file with the given name exists.

Declaration
[Obsolete("this method will be removed in 5.0")]
public override bool FileExists(string name)
Parameters
Type Name Description
string name
Returns
Type Description
bool
Overrides
See Also

FileLength(string)

Returns the length in bytes of a file in the directory.

Declaration
public override long FileLength(string name)
Parameters
Type Name Description
string name
Returns
Type Description
long
Overrides
See Also

Fsync(string)

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Declaration
protected virtual void Fsync(string name)
Parameters
Type Name Description
string name
See Also

GetLockID()

Return a string identifier that uniquely differentiates this Directory instance from other Directory instances. This ID should be the same if two Directory instances (even in different AppDomains and/or on different machines) are considered "the same index". This is how locking "scopes" to the right index.

Declaration
public override string GetLockID()
Returns
Type Description
string
Overrides
See Also

ListAll()

Lists all files (not subdirectories) in the directory.

Declaration
public override string[] ListAll()
Returns
Type Description
string[]
Overrides
See Also

ListAll(DirectoryInfo)

Lists all files (not subdirectories) in the directory. This method never returns null (throws IOException instead).

Declaration
public static string[] ListAll(DirectoryInfo dir)
Parameters
Type Name Description
DirectoryInfo dir
Returns
Type Description
string[]
Exceptions
Type Condition
DirectoryNotFoundException

if the directory does not exist, or does exist but is not a directory or is invalid (for example, it is on an unmapped drive).
SecurityException

The caller does not have the required permission.
See Also

OnIndexOutputClosed(FSIndexOutput)

Base class for Directory implementations that store index files in the file system.

There are currently three core subclasses:
  • SimpleFSDirectory is a straightforward implementation using FileStream, which is ideal for writing without using much RAM. However, it has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file.
  • NIOFSDirectory uses FileStream's positional seeking, which makes it slightly less efficient than using SimpleFSDirectory during reading, with similar write performance.
  • MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit runtime, or you are running on a 32 bit runtime but your index sizes are small enough to fit into the virtual memory space.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(string) method (or one of its overloads), to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(string) (or one of its overloads). For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory, but can be changed by passing in a custom LockFactory instance.

NOTE: Unlike in Java, it is not recommended to use Interrupt() in .NET in conjunction with an open FSDirectory because it is not guaranteed to exit atomically. Any lock statement or Enter(object) call can throw a ThreadInterruptedException, which makes shutting down unpredictable. To exit parallel tasks safely, we recommend using Tasks and "interrupt" them with CancellationTokens.
Declaration
protected virtual void OnIndexOutputClosed(FSDirectory.FSIndexOutput io)
Parameters
Type Name Description
FSDirectory.FSIndexOutput io
See Also

Open(DirectoryInfo)

Creates an FSDirectory instance, trying to pick the best implementation given the current environment. The directory returned uses the NativeFSLockFactory.

Currently this returns MMapDirectory for most Solaris and Windows 64-bit runtimes, NIOFSDirectory for other non-Windows runtimes, and SimpleFSDirectory for other runtimes on Windows. It is highly recommended that you consult the implementation's documentation for your platform before using this method.

NOTE: this method may suddenly change which implementation is returned from release to release, in the event that higher performance defaults become possible; if the precise implementation is important to your application, please instantiate it directly, instead. For optimal performance you should consider using MMapDirectory on 64 bit runtimes.

See FSDirectory.
Declaration
public static FSDirectory Open(DirectoryInfo path)
Parameters
Type Name Description
DirectoryInfo path
Returns
Type Description
FSDirectory
See Also

Open(DirectoryInfo, LockFactory)

Just like Open(DirectoryInfo), but allows you to also specify a custom LockFactory.

Declaration
public static FSDirectory Open(DirectoryInfo path, LockFactory lockFactory)
Parameters
Type Name Description
DirectoryInfo path
LockFactory lockFactory
Returns
Type Description
FSDirectory
See Also

Open(string)

Just like Open(DirectoryInfo), but allows you to specify the directory as a string.

Declaration
public static FSDirectory Open(string path)
Parameters
Type Name Description
string path

The path (to a directory) to open
Returns
Type Description
FSDirectory

An open FSDirectory
See Also

Open(string, LockFactory)

Just like Open(DirectoryInfo, LockFactory), but allows you to specify the directory as a string.

Declaration
public static FSDirectory Open(string path, LockFactory lockFactory)
Parameters
Type Name Description
string path

The path (to a directory) to open
LockFactory lockFactory
Returns
Type Description
FSDirectory

An open FSDirectory
See Also

SetLockFactory(LockFactory)

Set the LockFactory that this Directory instance should use for its locking implementation. Each * instance of LockFactory should only be used for one directory (ie, do not share a single instance across multiple Directories).

Declaration
public override void SetLockFactory(LockFactory lockFactory)
Parameters
Type Name Description
LockFactory lockFactory

instance of LockFactory.
Overrides
See Also

Sync(ICollection<string>)

Ensure that any writes to these files are moved to stable storage. Lucene uses this to properly commit changes to the index, to prevent a machine/OS crash from corrupting the index.

NOTE: Clients may call this method for same files over and over again, so some impls might optimize for that. For other impls the operation can be a noop, for various reasons.

Declaration
public override void Sync(ICollection<string> names)
Parameters
Type Name Description
ICollection<string> names
Overrides
See Also

ToString()

For debug output.

Declaration
public override string ToString()
Returns
Type Description
string
Overrides
See Also

Implements

See Also