Package com.tangosol.net.cache

Class OverflowMap.Status

java.lang.Object
com.tangosol.net.cache.OverflowMap.Status
Direct Known Subclasses:
OverflowMap.ExpirableStatus
Enclosing class:
OverflowMap
protected static class OverflowMap.Status extends Object
The Status object is used to manage concurrency at the key level for the key-level operations against the Map, to track all the items in the front Map, to manage the state transition for operations occurring against the Map, and to coordinate events across multiple threads.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final int
    STATE_MASK_BACK
    Bitmask for entry in back.
    protected static final int
    STATE_MASK_EXISTS
    Bitmask for fields that would indicate that the Status represents an existent entry in the OverflowMap.
    protected static final int
    STATE_MASK_FRONT
    Bitmask for entry in front.
    protected static final int
    STATE_MASK_INSYNC
    Bitmask for value in front and back being in sync.
    protected static final int
    STATE_MASK_RETAIN
    Bitmask for fields that would indicate that the Status must not be discarded.
    protected static final int
    STATE_MASK_STATUS
    Bitmask for status (least significant three bits reserved).
    protected static final int
    STATUS_AVAILABLE
    Status: The Status object exists and no thread is currently performing processing against the associated entry.
    protected static final int
    STATUS_COMMITTING
    Status: The Status object represents an Entry that was very recently being processed, and is currently finalizing the results of that processing.
    protected static final int
    STATUS_INVALIDATED
    Status: The Status object has been discarded.
    protected static final int
    STATUS_PROCESSING
    Status: The Status object represents an Entry that is currently being processed.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Status()
    Construct a Status object.

  • Method Summary

    Modifier and Type
    Method
    Description
    MapEvent
    closeProcessing()
    Finish the processing of the entry for which this Status exists and proceed to the commit phase.
    protected boolean
    commitAndMaybeInvalidate()
    Finish the commit for the entry for which this Status exists.
    protected boolean
    extractFlag(int nMask)
    Extract a particular masked flag from the state of the Status object.
    protected int
    extractState(int nMask)
    Extract a particular masked value from the state of the Status object.
    protected MapEvent
    getBackEvent()
    For internal use only, return the current event from the back Map.
    String
    getDescription()
    Assemble a human-readable description.
    long
    getExpiry()
    Determine the expiry for the entry represented by this Status.
    protected MapEvent
    getFrontEvent()
    For internal use only, return the current event from the front Map.
    Thread
    getOwnerThread()
    Determine the thread that owns the Status object, if the Status object is processing or committing.
    protected int
    getState()
    Determine the state of the Status object.
    protected int
    getStatus()
    Determine the enumerated status of the Status object.
    boolean
    hasEvent()
    Determine if an event has occurred against the Entry for which this Status exists.
    boolean
    hasExpiry()
    Determine if this Status represents an entry that will automatically expire.
    boolean
    isAvailable()
    Determine if the Status object is available.
    boolean
    isBackUpToDate()
    Determine if the entry for which this Status exists has the same value in the front Map as in the back Map.
    boolean
    isCommitting()
    Determine if the Status object represents an Entry that has been processed and the results of that processing are being committed.
    protected boolean
    isDiscardable()
    Determine if this Status object can be discarded.
    boolean
    isEntryExistent()
    Determine if the entry for which this Status exists is present in the front map or the back map.
    boolean
    isEntryInBack()
    Determine if the entry for which this Status exists is present in the back map.
    boolean
    isEntryInFront()
    Determine if the entry for which this Status exists is present in the front map.
    boolean
    isExpired()
    Determine if this Status represents an entry that will automatically expire.
    boolean
    isOwnedByCurrentThread()
    Determine if the current thread owns this Status object.
    boolean
    isProcessing()
    Determine if the Status object represents an Entry that is currently being processed.
    boolean
    isValid()
    Determine if the Status object is valid.
    boolean
    registerBackEvent(MapEvent evt)
    Register a MapEvent that has been raised by the back Map against the same key for which this Status object exists.
    boolean
    registerFrontEvent(MapEvent evt)
    Register a MapEvent that has been raised by the front Map against the same key for which this Status object exists.
    protected void
    setBackEvent(MapEvent evt)
    For internal use only, store the current event from the back Map.
    void
    setBackUpToDate(boolean fUpToDate)
    Specify that the value stored in the back Map is known to be up to date (not needing to be written to the back if evicted from the front).
    void
    setEntryInBack(boolean fEntryInBack)
    Specify whether the entry for which this Status exists is present in the back map.
    void
    setEntryInFront(boolean fEntryInFront)
    Specify whether the entry for which this Status exists is present in the front map.
    void
    setExpiry(long ldtExpires)
    Specify the expiry for the entry represented by this Status.
    protected void
    setFrontEvent(MapEvent evt)
    For internal use only, store the current event from the front Map.
    protected void
    setOwnerThread(Thread thread)
    Specify the thread that owns the Status object.
    protected void
    setState(int nState)
    Specify the state of the Status object.
    protected void
    setStatus(int nStatus)
    Determine the enumerated state of the Status object.
    MapEvent
    takeBackEvent()
    Obtain the most recent back Map event that has occurred against the Entry for which this Status exists.
    MapEvent
    takeEvent()
    Obtain the most recent event that has occurred against the Entry for which this Status exists.
    MapEvent
    takeFrontEvent()
    Obtain the most recent front Map event that has occurred against the Entry for which this Status exists.
    String
    toString()
    Returns a string representation of the object.
    protected void
    updateFlag(int nMask, boolean f)
    Update a particular masked flag within the state of the Status object.
    protected void
    updateState(int nMask, int nValue)
    Update a particular masked value within the state of the Status object.
    protected MapEvent
    waitForAvailable()
    Wait for the Entry that this Status represents to become available.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • STATE_MASK_STATUS

      protected static final int STATE_MASK_STATUS
      Bitmask for status (least significant three bits reserved).
      See Also:

    • STATE_MASK_FRONT

      protected static final int STATE_MASK_FRONT
      Bitmask for entry in front.
      See Also:

    • STATE_MASK_BACK

      protected static final int STATE_MASK_BACK
      Bitmask for entry in back.
      See Also:

    • STATE_MASK_INSYNC

      protected static final int STATE_MASK_INSYNC
      Bitmask for value in front and back being in sync.
      See Also:

    • STATE_MASK_EXISTS

      protected static final int STATE_MASK_EXISTS
      Bitmask for fields that would indicate that the Status represents an existent entry in the OverflowMap.
      See Also:

    • STATE_MASK_RETAIN

      protected static final int STATE_MASK_RETAIN
      Bitmask for fields that would indicate that the Status must not be discarded.
      See Also:

    • STATUS_AVAILABLE

      protected static final int STATUS_AVAILABLE
      Status: The Status object exists and no thread is currently performing processing against the associated entry.
      See Also:

    • STATUS_PROCESSING

      protected static final int STATUS_PROCESSING
      Status: The Status object represents an Entry that is currently being processed.
      See Also:

    • STATUS_COMMITTING

      protected static final int STATUS_COMMITTING
      Status: The Status object represents an Entry that was very recently being processed, and is currently finalizing the results of that processing.
      See Also:

    • STATUS_INVALIDATED

      protected static final int STATUS_INVALIDATED
      Status: The Status object has been discarded.
      See Also:

  • Constructor Details

    • Status

      public Status()
      Construct a Status object.

  • Method Details

    • getStatus

      protected int getStatus()
      Determine the enumerated status of the Status object. This value is intended for internal and debugging use only, and should have no meaning to any external consumer.
      Returns:
      a number corresponding to the enumeration of states as represented by the STATUS_*

    • setStatus

      protected void setStatus(int nStatus)
      Determine the enumerated state of the Status object. This value is intended for internal and debugging use only, and should have no meaning to any external consumer.
      Parameters:
      nStatus - a number corresponding to one of the enumeration represented by the STATUS_* constants

    • isValid

      public boolean isValid()
      Determine if the Status object is valid. A Status object can be discarded (no longer used), in which case it will not be valid.
      Returns:
      true iff the Status object is still valid

    • isAvailable

      public boolean isAvailable()
      Determine if the Status object is available. A Status object is available if it is valid and no thread is currently processing the entry for which this Status object exists.
      Returns:
      true iff the Status object is available

    • isProcessing

      public boolean isProcessing()
      Determine if the Status object represents an Entry that is currently being processed.
      Returns:
      true iff the entry represented by this Status object is being processed

    • isCommitting

      public boolean isCommitting()
      Determine if the Status object represents an Entry that has been processed and the results of that processing are being committed. The "committing" status implies that no other thread is allowed to do anything related to the entry that this Status represents.
      Returns:
      true iff the entry represented by this Status object is being committed

    • getOwnerThread

      public Thread getOwnerThread()
      Determine the thread that owns the Status object, if the Status object is processing or committing.
      Returns:
      the owning thread, or null

    • setOwnerThread

      protected void setOwnerThread(Thread thread)
      Specify the thread that owns the Status object. For internal use only.
      Parameters:
      thread - the owning thread, or null

    • isOwnedByCurrentThread

      public boolean isOwnedByCurrentThread()
      Determine if the current thread owns this Status object.
      Returns:
      true iff the current thread owns this Status object

    • isEntryInFront

      public boolean isEntryInFront()
      Determine if the entry for which this Status exists is present in the front map.
      Returns:
      true iff the entry is stored in the front map

    • setEntryInFront

      public void setEntryInFront(boolean fEntryInFront)
      Specify whether the entry for which this Status exists is present in the front map.
      Parameters:
      fEntryInFront - pass true if the entry is stored in the front map, false if not

    • isEntryInBack

      public boolean isEntryInBack()
      Determine if the entry for which this Status exists is present in the back map.
      Returns:
      true iff the entry is stored in the back map

    • setEntryInBack

      public void setEntryInBack(boolean fEntryInBack)
      Specify whether the entry for which this Status exists is present in the back map.
      Parameters:
      fEntryInBack - pass true if the entry is stored in the back map, false if not

    • isEntryExistent

      public boolean isEntryExistent()
      Determine if the entry for which this Status exists is present in the front map or the back map.
      Returns:
      true iff the entry is stored in either the front or the back map

    • isBackUpToDate

      public boolean isBackUpToDate()
      Determine if the entry for which this Status exists has the same value in the front Map as in the back Map.
      Returns:
      true iff the value exists in the back Map, and the value in the front Map is the same as the value in the back Map

    • setBackUpToDate

      public void setBackUpToDate(boolean fUpToDate)
      Specify that the value stored in the back Map is known to be up to date (not needing to be written to the back if evicted from the front).
      Parameters:
      fUpToDate - the flag indicate back up to date

    • getFrontEvent

      protected MapEvent getFrontEvent()
      For internal use only, return the current event from the front Map. All handling of synchronization etc. is the responsibility of the sub-class.
      Returns:
      the cummulative front Map event for the Entry represented by this Status object, or null if there were no events

    • setFrontEvent

      protected void setFrontEvent(MapEvent evt)
      For internal use only, store the current event from the front Map. All handling of synchronization etc. is the responsibility of the sub-class.
      Parameters:
      evt - the cummulative front Map event for the Entry represented by this Status object, or null to clear the event

    • getBackEvent

      protected MapEvent getBackEvent()
      For internal use only, return the current event from the back Map. All handling of synchronization etc. is the responsibility of the sub-class.
      Returns:
      the cummulative back Map event for the Entry represented by this Status object, or null if there were no events

    • setBackEvent

      protected void setBackEvent(MapEvent evt)
      For internal use only, store the current event from the back Map. All handling of synchronization etc. is the responsibility of the sub-class.
      Parameters:
      evt - the cummulative back Map event for the Entry represented by this Status object, or null to clear the event

    • hasEvent

      public boolean hasEvent()
      Determine if an event has occurred against the Entry for which this Status exists.
      Returns:
      true iff an event is held by the Status

    • takeFrontEvent

      public MapEvent takeFrontEvent()
      Obtain the most recent front Map event that has occurred against the Entry for which this Status exists.
      Returns:
      the cummulative front Map event for the Entry represented by this Status object, or null if there were no events

    • takeBackEvent

      public MapEvent takeBackEvent()
      Obtain the most recent back Map event that has occurred against the Entry for which this Status exists.
      Returns:
      the cummulative back Map event for the Entry represented by this Status object, or null if there were no events

    • takeEvent

      public MapEvent takeEvent()
      Obtain the most recent event that has occurred against the Entry for which this Status exists. If both the front and the back Map have event listeners which register events with the Status object, then the event could be from either the front or the back Map. If events have occurred on both the front and back Maps, the event from the front Map will be returned and the event from the back Map will be discarded; this can be explained by the fact that the front Map overlays the back Map, and thus the back Map events can be safely ignored if a front Map event has occurred. (This is possible because the back Map content is not monitored strictly, but the front Map content is.)
      Returns:
      the cummulative event for the Entry represented by this Status object, or null if there were no events

    • getExpiry

      public long getExpiry()
      Determine the expiry for the entry represented by this Status.
      Returns:
      the expiry, or 0L if there is no expiry

    • setExpiry

      public void setExpiry(long ldtExpires)
      Specify the expiry for the entry represented by this Status.
      Parameters:
      ldtExpires - the expiry, or 0L if the entry should not expire

    • hasExpiry

      public boolean hasExpiry()
      Determine if this Status represents an entry that will automatically expire.
      Returns:
      true iff the Status is for an entry that will expire

    • isExpired

      public boolean isExpired()
      Determine if this Status represents an entry that will automatically expire.
      Returns:
      true iff the Status is for an entry that will expire

    • isDiscardable

      protected boolean isDiscardable()
      Determine if this Status object can be discarded.

      This is an internal method.

      Returns:
      true iff this Status object can be discarded

    • getDescription

      public String getDescription()
      Assemble a human-readable description.
      Returns:
      a description of this Status object

    • toString

      public String toString()
      Returns a string representation of the object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the object

    • waitForAvailable

      protected MapEvent waitForAvailable()
      Wait for the Entry that this Status represents to become available. Once it becomes available, the current thread will automatically become the owner and the status will be changed to "processing".
      Returns:
      whatever event was deferred for this Status which the caller must handle

    • closeProcessing

      public MapEvent closeProcessing()
      Finish the processing of the entry for which this Status exists and proceed to the commit phase. The act of closing processing collects any side-effects to the corresponding front Map Entry (either from this or other threads) as a single event.
      Returns:
      all events that have occurred on this or other threads for the front Map Entry represented by this Status object while this Status object was "processing", or null if there were no events

    • commitAndMaybeInvalidate

      protected boolean commitAndMaybeInvalidate()
      Finish the commit for the entry for which this Status exists. If there are any threads waiting on the entry for which this Status exists, one will be notified that the Status is now available. If the entry for which this Status object exists is contained in the front Map, then it will proceed to the available phase. Otherwise, the Status will be invalidated and discarded from the Status registry.

      This is an internal method. It requires the caller to have first synchronized on the registry (Map) that contains the Status objects before calling this method (or otherwise synchronizing on this Status object). Failure to follow this rule will result in deadlock and/or exceptional conditions.

      Returns:
      true iff this Status object has invalidated itself

    • registerFrontEvent

      public boolean registerFrontEvent(MapEvent evt)
      Register a MapEvent that has been raised by the front Map against the same key for which this Status object exists. If an event has previously been registered, the previous and new event are merged into a single merged event that incorporates the data from both events.

      For truly predictable behavior, this requires that the front Map implementation be synchronized during the raising of events, such that an event will only be raised from the front Map on one thread at a time. The event listener (for the overflow map) must then synchronize on this Status object (to verify that it is indeed valid before registering the event) and the register the event while holding that synchronization. If the registration returns a deferred indicator, then the

      Parameters:
      evt - the event that has occurred against an entry in the front Map with the same key which this Status object represents
      Returns:
      true iff the event processing has been deferred, implying that this Status object should be registered in a list of Status objects that have events that need to be handled

    • registerBackEvent

      public boolean registerBackEvent(MapEvent evt)
      Register a MapEvent that has been raised by the back Map against the same key for which this Status object exists. If an event has previously been registered, the previous and new event are merged into a single merged event that incorporates the data from both events.
      Parameters:
      evt - the event that has occurred against an entry in the back Map with the same key which this Status object represents
      Returns:
      true iff the event processing has been deferred, implying that this Status object should be registered in a list of Status objects that have events that need to be handled

    • getState

      protected int getState()
      Determine the state of the Status object. This value is intended for internal and debugging use only, and should have no meaning to any external consumer.
      Returns:
      the bit-packed state of the Status object

    • setState

      protected void setState(int nState)
      Specify the state of the Status object. This value is intended for internal and debugging use only, and should have no meaning to any external consumer.
      Parameters:
      nState - the new bit-packed state for the Status object

    • extractState

      protected int extractState(int nMask)
      Extract a particular masked value from the state of the Status object.
      Parameters:
      nMask - the mask identifying the value
      Returns:
      the extracted value

    • updateState

      protected void updateState(int nMask, int nValue)
      Update a particular masked value within the state of the Status object.
      Parameters:
      nMask - the mask of bits to store the value within
      nValue - the value to store inside that mask

    • extractFlag

      protected boolean extractFlag(int nMask)
      Extract a particular masked flag from the state of the Status object.
      Parameters:
      nMask - the mask identifying the flag
      Returns:
      the extracted flag as a boolean

    • updateFlag

      protected void updateFlag(int nMask, boolean f)
      Update a particular masked flag within the state of the Status object.
      Parameters:
      nMask - the mask of flag bit to store the flag within
      f - the boolean value to store within that mask