|
Oracle® Coherence Java API Reference Release 3.7.1.0 E22843-01 |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
com.tangosol.io.journal.AbstractJournalRM
com.tangosol.io.journal.RamJournalRM
public class RamJournalRM
A RamJournalRM manages memory buffers for journal-based storage in memory, and acts as a shared resource for any number of journals that share a common configuration. While the RamJournalRM can be used by itself, it is intended to be used with a FlashJournalRM instance: So that large objects can be stored using flash; to allow for spill-over when the amount of total memory allocated to the RAM journal is used; and to handle the case when the journal "garbage collection" is temporarily not able to keep up with demand.
To use the Resource Manager, configure it (either by XML using configure(XmlElement)
, or by calling the appropriate setter methods such as setFlashJournalRM(FlashJournalRM)
). Once configured, start the Resource Manager via the AbstractJournalRM.start()
method, and then obtain BinaryStore
instances via the AbstractJournalRM.createBinaryStore()
method. When a BinaryStore instance is no longer required, dispose of it via the Disposable
interface, and similarly stop()
or AbstractJournalRM.dispose()
of the Resource Manager when it is no longer needed to ensure that any resources it allocated are cleaned up and released.
The limits on the journal are as follows:
Note that with a flash journal backing up the RAM journal, the limits have a different meaning:
Note that, outside of the initial configuration, there is no difference in the use of the RAM journal with or without the flash journal; the combination of the RAM journal with the flash journal is transparent to the clients, with the only obvious difference being the significantly reduced possibility of an exception due to the RAM being exhausted.
Nested Class Summary | |
---|---|
protected class |
RamJournalRM.BufferPool A pooling implementation for WriteBuffer objects. |
protected class |
RamJournalRM.FlashConsumer The FlashConsumer is a conduit between this RamJournalRM and the FlashJournalRM, allowing this journal to read/write to/from the other flash journal, and for the flash journal to notify this journal of lifecycle and other events. |
protected class |
RamJournalRM.JournalFile A JournalFile is created for each RAM buffer used to store the journal contents. |
protected class |
RamJournalRM.JournalImpl A Journal implementation managed by this Journal Resource Manager. |
Nested classes/interfaces inherited from class com.tangosol.io.journal.AbstractJournalRM |
---|
AbstractJournalRM.CollectorDaemon |
Field Summary | |
---|---|
static double |
DFT_COLLECT_PCT Default collection factor (collect files that are 84% or less utilized). |
static long |
DFT_FILE_SIZE Default size of a "file" i.e. a buffer (2MB). |
static long |
DFT_POOL_SIZE Default pool size (16MB). |
static long |
DFT_TOTAL_SIZE Default total size of RAM used (1GB). |
static int |
DFT_VALUE_SIZE Default maximum value size (16KB). |
protected long |
m_cbMaxPool The maximum total amount of unused RAM buffers that the journal will pool. |
protected long |
m_cbMaxRam The maximum total amount of RAM that the journal will allocate. |
protected RamJournalRM.FlashConsumer |
m_flash The conduit between this RAM journal resource manager and the flash journal resource manager. |
protected boolean |
m_fUseNioRam The option to use NIO buffers instead of on-heap byte arrays. |
protected FlashJournalRM |
m_jrnlrm A reference to a flash journal resource manager to use to read/write to/from flash for data that doesn't fit in memory. |
protected RamJournalRM.BufferPool |
m_pool The buffer pool. |
protected static long |
MASK_FILE_ID The 64-bit bitmask for the file index. |
protected static long |
MASK_LENGTH The 64-bit bitmask for the value length. |
protected static long |
MASK_OFFSET The 64-bit bitmask for the value offset. |
protected static long |
MASK_RAM_FLAG The 64-bit bitmask for the RAM flag. |
static long |
MAX_FILE_SIZE Maximum size of a "file" i.e. a buffer (2GB). |
static long |
MAX_POOL_SIZE Maximum pool size (64GB). |
static long |
MAX_TOTAL_SIZE Maximum total size of RAM used (64GB). |
static int |
MAX_VALUE_SIZE Maximum value size (4MB). |
static long |
MIN_FILE_SIZE Minimum maximum size of a "file" i.e. a buffer (1MB). |
static long |
MIN_TOTAL_SIZE Minimum maximum total size of RAM used (16MB). |
protected static int |
SHIFT_FILE_ID The location of the file id within the ticket. |
protected static int |
SHIFT_LENGTH The location of the value-length within the ticket. |
protected static int |
SHIFT_OFFSET The location of the value-offset within the ticket. |
protected static int |
SHIFT_RAM_FLAG The location of the RAM flag within the ticket. |
Fields inherited from class com.tangosol.io.journal.AbstractJournalRM |
---|
m_ajournalfile, m_cbMaxFile, m_cbMaxValue, m_cJournalFiles, m_daemonCollector, m_dflHighestLoadFactor, m_dflLoadFactorGC, m_jrnlfile, m_loader, m_nState, m_setJournals, m_xmlConfig, MASK_COMPACT_FLAG, MASK_COMPACT_LENGTH, MAX_COLLECT_PCT, MIN_COLLECT_PCT, SHIFT_COMPACT_FLAG, SHIFT_COMPACT_LENGTH, STATE_CONFIGURED, STATE_INITIAL, STATE_RUNNING, STATE_STOPPED, STATE_STOPPING |
Constructor Summary | |
---|---|
RamJournalRM(Cluster cluster) Construct a RAMJournalRM. |
Method Summary | |
---|---|
protected void |
applyConfig(java.lang.String sName, XmlElement xmlConfig) Parse the XML configuration for the specified setting name, and configure the Journal Resource Manager accordingly. |
void |
configure(XmlElement xml) Configure the controllable service. |
protected long |
encodeTicket(int nFile, long of, int cb) Encode a file number, offset and length into a "ticket". |
protected int |
extractFileId(long lTicket) Extract a file index (a file ID) from the passed ticket. |
protected int |
extractLength(long lTicket) Extract a file offset from the passed ticket. |
protected long |
extractOffset(long lTicket) Extract a file offset from the passed ticket. |
int |
getBacklogCount() Determine the number of serialized values that have not yet been persisted to disk. |
int |
getBacklogSize() Determine the total size in bytes of the serialized values that have not yet been persisted to disk. |
protected RamJournalRM.BufferPool |
getBufferPool() Obtain the BufferPool instance. |
int |
getBufferSize() Determine the size of the buffers used to write a chunk of data at a time to an underlying journal file. |
protected double |
getDefaultCollectorLoadFactor() Determine the default percentage at which a file is eligible for garbage collection. |
protected long |
getDefaultMaxFileSize() Determine the default maximum file size for this Journal Resource Manager. |
protected int |
getDefaultMaxValueSize() Determine the default maximum value size for this Journal Resource Manager. |
protected java.lang.String |
getDescription() Format the object attributes into a String for inclusion in the String returned from the AbstractJournalRM.toString() method. |
protected long |
getEvacuationMask() Obtain the bit mask that is used to identify tickets that need to be evacuated for a particular file id. |
protected RamJournalRM.FlashConsumer |
getFlashConsumer() Obtain the FlashConsumer object used to read/write flash. |
protected Journal |
getFlashJournal() Obtain the Journal used to read/write flash. |
FlashJournalRM |
getFlashJournalRM() Obtain the FlashJournalRM used to store large values or whatever values don't fit in the configured amount of RAM. |
protected RamJournalRM.JournalFile |
getJournalFile(int nFileId) Obtain a JournalFile by its ID. |
int |
getMaxBacklogSize() Determine the maximum allowable size, in bytes, of the backlog; when the backlog reaches this level, writes are delayed until the backlog drops below its maximum. |
protected int |
getMaxJournalFiles() Determine the maximum number of journal files. |
long |
getMaxPoolSize() Determine the maximum size (in bytes) of the buffers that can be held by the pool. |
long |
getMaxTotalRam() Determine the total amount, in bytes, of RAM that will be used for the Journal. |
protected long |
getMinCollectorSleepMillis() Determine the minimum sleep cycle between collections. |
protected float |
getPercentageAsFraction(java.lang.String sSize) Converts the string argument, while interpreting it as a percentage value in the range of 1-99 to a float. |
int |
getPoolSize() Determine the size (in bytes) of the buffers that are currently available in the pool. |
protected java.lang.String |
getTicketDescription(long lTicket) Format the information encoded in a ticket into a debug string. |
protected RamJournalRM.BufferPool |
instantiateBufferPool() Factory: Instantiate a pool of buffers. |
protected RamJournalRM.FlashConsumer |
instantiateConsumer() Factory: Instantiate a FlashConsumer object. |
protected RamJournalRM.JournalImpl |
instantiateJournal() Factory: Instantiate a JournalImpl object. |
protected RamJournalRM.JournalFile |
instantiateJournalFile(int nFile) Factory: Instantiate a JournalFile or subclass thereof. |
protected boolean |
isCompact(long lTicket) Determine if the ticket is in the compact form. |
protected boolean |
isDedupEnabled() Determine if this journal resource manager should de-dup the keys that its JournalBinaryStore instances are managing. |
protected boolean |
isFlash(long lTicket) Determine if the ticket is neither in compact or RAM form. |
boolean |
isNioRam() Determine if the journal will use direct buffers (NIO RAM) instead of on-heap buffers (byte arrays). |
protected boolean |
isRam(long lTicket) Determine if the ticket is in the RAM form. |
protected boolean |
isSingleEvacuation() Determine if this journal resource manager should only evacuate one single JournalFile (at the most) per collection cycle. |
void |
setFlashJournalRM(FlashJournalRM jrnlrm) Configure the FlashJournalRM to use to store large values, or to store all values once the configured amount of RAM has been filled. |
void |
setMaxFileSize(long cb) Configure the maximum size of the underlying journal files. |
void |
setMaxPoolSize(long cb) Configure the size of the buffers pool. |
void |
setMaxTotalRam(long cb) Configure the total amount of RAM that will be used for the journal. |
void |
setMaxValueSize(int cb) Specify the maximum size, in bytes, of Binary values to store. |
void |
setNioRam(boolean fUseNioRam) Configure the journal to use direct buffers (NIO RAM) versus on-heap buffers (byte arrays) to store the journal data. |
protected void |
startThreads() Create and start the various threads used by this Journal Resource Manager. |
void |
stop() Hard-stop the controllable service. |
Field Detail |
---|
protected static final int SHIFT_RAM_FLAG
protected static final long MASK_RAM_FLAG
The RAM flag is the bit that signifies that the ticket was produced by the RAM Journal Resource Manager, as opposed to either a "real" compact ticket or a delegated flash ticket.
protected static final int SHIFT_FILE_ID
protected static final long MASK_FILE_ID
protected static final int SHIFT_OFFSET
protected static final long MASK_OFFSET
protected static final int SHIFT_LENGTH
protected static final long MASK_LENGTH
public static final long MIN_FILE_SIZE
public static final long MAX_FILE_SIZE
public static final long DFT_FILE_SIZE
public static final long MIN_TOTAL_SIZE
public static final long MAX_TOTAL_SIZE
public static final long DFT_TOTAL_SIZE
public static final int MAX_VALUE_SIZE
public static final int DFT_VALUE_SIZE
public static final long MAX_POOL_SIZE
public static final long DFT_POOL_SIZE
public static final double DFT_COLLECT_PCT
protected long m_cbMaxRam
protected boolean m_fUseNioRam
protected long m_cbMaxPool
protected RamJournalRM.BufferPool m_pool
protected FlashJournalRM m_jrnlrm
protected RamJournalRM.FlashConsumer m_flash
Constructor Detail |
---|
public RamJournalRM(Cluster cluster)
cluster
- the Cluster
for which the RamJournalRM
is storing dataMethod Detail |
---|
public void configure(XmlElement xml)
This method can only be called before the controllable service is started.
The Journal Resource Manager supports the following configuration options:
The RAM Journal Resource Manager supports the following additional configuration options:
Note that with a flash journal backing up the RAM journal, some of the settings have a slightly different meaning:
To configure the RAM journal so that it is backed by a flash journal, use the setFlashJournalRM(FlashJournalRM)
method to provide a reference to the flash journal before configuring the RAM journal.
configure
in interface Controllable
configure
in class AbstractJournalRM
xml
- an XmlElement carrying configuration information specific to the Controllable objectpublic void stop()
Controllable.shutdown()
for normal service termination. Calling this method for a service that has already stopped has no effect.stop
in interface Controllable
stop
in class AbstractJournalRM
public int getBacklogCount()
This property is specific to a FlashJournalRM
implementation.
public int getBacklogSize()
This property is specific to a FlashJournalRM
implementation.
public int getMaxBacklogSize()
This property is specific to a FlashJournalRM
implementation.
public int getPoolSize()
This property is specific to a FlashJournalRM
implementation.
public long getMaxTotalRam()
This property is specific to a RamJournalRM
implementation.
public boolean isNioRam()
This property is specific to a RamJournalRM
implementation.
public long getMaxPoolSize()
public int getBufferSize()
This property is specific to a FlashJournalRM
implementation.
public void setMaxValueSize(int cb)
By default it is set to 16KB, as defined by DFT_VALUE_SIZE
, with the maximum supported size being 4MB, as defined by MAX_VALUE_SIZE
. The MaxValueSize must be no larger than half of the MaxFileSize.
Note: This value can be modified while the ResourceManager is running.
setMaxValueSize
in class AbstractJournalRM
cb
- the maximum allowable size for a Binary value, or zero to specify no configured maximum for the value sizepublic void setMaxFileSize(long cb)
Note: This value can only be set before the ResourceManager is started.
The maximum file size cannot exceed 1/2 of the maximum total RAM setting, since the journal is segmented into files, all of which must add up to a total size smaller than the maximum total RAM setting. If setting both MaxFileSize and MaxTotalRam, set the MaxTotalRam first.
This is an advanced setting.
setMaxFileSize
in class AbstractJournalRM
cb
- the maximum size, in bytes, for journal filespublic void setMaxTotalRam(long cb)
Note: This value can only be set before the ResourceManager is started.
cb
- the maximum number of bytes that will be allocated for journal storagepublic void setNioRam(boolean fUseNioRam)
fUseNioRam
- pass true to use NIO direct buffers off the heap, or false to use byte arrays on the heappublic void setMaxPoolSize(long cb)
DFT_POOL_SIZE
, with a maximum defined by MAX_POOL_SIZE
and a minimum of zero.
Note: This value can only be set before the ResourceManager is started.
cb
- the size, in bytes, for the buffer poolpublic FlashJournalRM getFlashJournalRM()
public void setFlashJournalRM(FlashJournalRM jrnlrm)
Note: This value can only be set before the ResourceManager is started.
jrnlrm
- a FlashJournalRM instanceprotected void applyConfig(java.lang.String sName, XmlElement xmlConfig)
applyConfig
in class AbstractJournalRM
sName
- the name of the XML settingxmlConfig
- the XML element containing the settingprotected float getPercentageAsFraction(java.lang.String sSize)
sSize
- the string argument containing a percentage valuejava.lang.IllegalArgumentException
- if the string can't be interpreted as a percentage valueprotected void startThreads()
startThreads
in class AbstractJournalRM
protected java.lang.String getDescription()
AbstractJournalRM.toString()
method.getDescription
in class AbstractJournalRM
protected int getMaxJournalFiles()
getMaxJournalFiles
in class AbstractJournalRM
protected long getDefaultMaxFileSize()
getDefaultMaxFileSize
in class AbstractJournalRM
protected int getDefaultMaxValueSize()
getDefaultMaxValueSize
in class AbstractJournalRM
protected double getDefaultCollectorLoadFactor()
getDefaultCollectorLoadFactor
in class AbstractJournalRM
protected long getMinCollectorSleepMillis()
getMinCollectorSleepMillis
in class AbstractJournalRM
protected boolean isDedupEnabled()
isDedupEnabled
in class AbstractJournalRM
protected boolean isSingleEvacuation()
isSingleEvacuation
in class AbstractJournalRM
protected Journal getFlashJournal()
protected RamJournalRM.JournalImpl instantiateJournal()
instantiateJournal
in class AbstractJournalRM
protected RamJournalRM.FlashConsumer instantiateConsumer()
protected RamJournalRM.FlashConsumer getFlashConsumer()
protected RamJournalRM.JournalFile getJournalFile(int nFileId)
getJournalFile
in class AbstractJournalRM
nFileId
- the file id (0-511)protected RamJournalRM.JournalFile instantiateJournalFile(int nFile)
instantiateJournalFile
in class AbstractJournalRM
nFile
- the file number in the range 0-511 (inclusive)protected boolean isCompact(long lTicket)
isCompact
in class AbstractJournalRM
lTicket
- a "ticket" that was created by the Journalprotected boolean isRam(long lTicket)
lTicket
- a "ticket" that was returned previously by the Journalprotected boolean isFlash(long lTicket)
lTicket
- a "ticket" that was returned previously by the Journalprotected long getEvacuationMask()
getEvacuationMask
in class AbstractJournalRM
protected int extractFileId(long lTicket)
extractFileId
in class AbstractJournalRM
lTicket
- a "ticket" that was created by the Journalprotected long extractOffset(long lTicket)
extractOffset
in class AbstractJournalRM
lTicket
- a "ticket" that was created by the Journalprotected int extractLength(long lTicket)
extractLength
in class AbstractJournalRM
lTicket
- a "ticket" that was created by the Journalprotected long encodeTicket(int nFile, long of, int cb)
encodeTicket
in class AbstractJournalRM
nFile
- a file number (aka a file index)of
- a value offsetcb
- a value lengthprotected java.lang.String getTicketDescription(long lTicket)
getTicketDescription
in class AbstractJournalRM
lTicket
- the ticket valueprotected RamJournalRM.BufferPool instantiateBufferPool()
protected RamJournalRM.BufferPool getBufferPool()
|
Oracle® Coherence Java API Reference Release 3.7.1.0 E22843-01 |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |