org.jnetstream.capture.file
Enum FileOptions.MemoryModel

java.lang.Object
  java.lang.Enum<FileOptions.MemoryModel>
      org.jnetstream.capture.file.FileOptions.MemoryModel

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<FileOptions.MemoryModel>

Enclosing interface:

FileOptions

public static enum FileOptions.MemoryModel
extends java.lang.Enum<FileOptions.MemoryModel>

Options for changing the memory model used by the implementation.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Enum Constant Summary

ByteArray
The prefetch buffer used is byte array based.

DirectBuffer
The prefetch buffer used is direct buffer allocation.

MappedFile
The prefetch buffer uses memory mapped file buffers.

Method Summary

static FileOptions.MemoryModel	valueOf(java.lang.String name) Returns the enum constant of this type with the specified name.
static FileOptions.MemoryModel[]	values() Returns an array containing the constants of this enum type, in the order they're declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ByteArray

public static final FileOptions.MemoryModel ByteArray

The prefetch buffer used is byte array based. A regular java byte array is allocated to hold contents of the file as its prefetched into memory. The buffer size for this type of model should be around the page-size or cluster-size.

See Also:

DirectBuffer, MappedFile

DirectBuffer

public static final FileOptions.MemoryModel DirectBuffer

The prefetch buffer used is direct buffer allocation. This type of buffer holds its memory outside the java VM and allows maniche native operations on it. The file contents are prefetched very efficiently by the underlying OS kernel into the buffer. The buffer size for this type of model should be larger then ByteArray, the default is 512KB.

See Also:

ByteArray, MappedFile

MappedFile

public static final FileOptions.MemoryModel MappedFile

The prefetch buffer uses memory mapped file buffers. Portions of the file are mapped by the kernel into physical memory using native OS functions and the data is directly accessed from the memory mapped buffers. This is the most efficient method as no data copies are done as the buffer addresses directly into the kernel buffer space. The buffer size for this type of model should be as large as possible. The default is 2MB and can get set as high as is acceptable to the user. Testing reveils no performance gain on buffers larger them 130MB, but this could be different on different machines. The reason for the large buffer size is that memory mapping a file is very time consuming, the larger the mapped buffer the less frequently it will have to be done. Memory mapping buffers lower then 512KB will have detrimental performance as compared to other memory models.

Note: there are several outstanding issues with memomry mapped file buffers in current releases of java. The biggest issue is that once a buffer has been mapped, it can not be unmapped predictably from memory ( Sun Bug#4774038. A file that has mapped memory buffer can not be truncated or enlarged. Therefore parts of the MutableFileCapture API fail when this mode was used on a file in this or any other session. Closing of the open file, does not unmap the memory mapped file buffers and they continue to exist and block functionality, even if there are no references to them from within the VM. Every attempt is made by this implementation to unmap the buffers by explicit calls to GC and cleaner Finalilzers, but there is no guarrantee that the buffers will be unmapped by these efforts. Therefore the user is warned to use the memory mapped buffers where appropriated, ie. read-only operations. The memory mapped model provides increadible level of performance and should be used where appropriate.

Also note that the mapping file to memory is very intensive and is typically beneficial on very large files to pull large chunks of it into memory, but incases where a small file will be iterated over and over, it may be more beneficial to change the default model to MappedFile, take the penalty once for mapping the entire file into memory and then reap the benefits of accessing the file content very fast. Same goes for the DirectBuffer model.

See Also:

ByteArray, DirectBuffer

Method Detail

values

public static final FileOptions.MemoryModel[] values()

Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants as follows:

for(FileOptions.MemoryModel c : FileOptions.MemoryModel.values())
        System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they're declared

valueOf

public static FileOptions.MemoryModel valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name