Package com.tangosol.net.cache

Class SimpleOverflowMap.Status

  • Enclosing class:
    SimpleOverflowMap
    protected static class SimpleOverflowMap.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 int STATE_MASK_FRONT
      Bitmask for entry in front.
      protected static int STATE_MASK_INSYNC
      Bitmask for value in front and back being in sync.
      protected static int STATE_MASK_RETAIN
      Bitmask for fields that would indicate that the Status must not be discarded.
      protected static int STATE_MASK_STATUS
      Bitmask for status (least significant three bits reserved).
      protected static int STATE_VALUE_RETAIN
      Bit values for fields that would indicate that the Status can be discarded.
      protected static int STATUS_AVAILABLE
      Status: The Status object exists and no thread is currently performing processing against the associated entry.
      protected static 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 int STATUS_INVALIDATED
      Status: The Status object has been discarded.
      protected static int STATUS_PROCESSING
      Status: The Status object represents an Entry that is currently being processed.
      protected static int STATUS_RESERVED
      Status: The Status object has been reserved for processing by a thread but is not yet processing.

    • Constructor Summary

      Constructors 
      Constructor Description
      Status()
      Construct a Status object for a specific key.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      String getDescription()
      Assemble a human-readable description.
      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 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 isEntryInFront()
      Determine if the entry for which this Status exists is present in the front map.
      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 isReserved()
      Determine if the Status object is reserved.
      boolean isValid()
      Determine if the Status object is valid.
      protected MapEvent mergeEvents​(MapEvent evtOld, MapEvent evtNew)
      Merge two events that have been raised in sequence from a given map.
      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 boolean requestReservation()
      Attempt to reserve the Status by marking it as committing if it is available.
      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 setEntryInFront​(boolean fEntryInFront)
      Specify whether the entry for which this Status exists is present in the front map.
      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 takeEvent()
      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 useReservation()
      After having successfully made a reservation, this method completes the reservation process by setting the status to processing for the thread that made the reservation.
      protected MapEvent waitForAvailable()
      Wait for the Entry that this Status represents to become available.
      protected void waitForReservationDecision()
      Wait for the Entry that this Status represents to no longer be reserved.

    • Field Detail

      • STATE_MASK_STATUS

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

      • STATE_MASK_FRONT

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

      • STATE_MASK_INSYNC

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

      • 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:
        Constant Field Values

      • STATUS_RESERVED

        protected static final int STATUS_RESERVED
        Status: The Status object has been reserved for processing by a thread but is not yet processing.
        See Also:
        Constant Field Values

      • STATUS_PROCESSING

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

      • 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:
        Constant Field Values

      • STATUS_INVALIDATED

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

      • 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:
        Constant Field Values

      • STATE_VALUE_RETAIN

        protected static final int STATE_VALUE_RETAIN
        Bit values for fields that would indicate that the Status can be discarded.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Status

        public Status()
        Construct a Status object for a specific key.

    • Method Detail

      • 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

      • isReserved

        public boolean isReserved()
        Determine if the Status object is reserved.
        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

      • 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 - whether the stored value is 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

      • 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

      • takeEvent

        public MapEvent takeEvent()
        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

      • 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".

        This is an internal method. It requires the caller to have synchronized on the Status object before calling this method.

        Returns:
        whatever event was deferred for this Status which the caller must handle

      • requestReservation

        protected boolean requestReservation()
        Attempt to reserve the Status by marking it as committing if it is available. If successful, the caller must subsequently either call useReservation() or commitAndMaybeInvalidate() (to cancel the reservation).

        This is an internal method.

        Returns:
        true if the reservation was made successfull, false if another thread already owns this Status object

      • waitForReservationDecision

        protected void waitForReservationDecision()
        Wait for the Entry that this Status represents to no longer be reserved.

        This is an internal method. It requires the caller to have synchronized on the Status object before calling this method.

      • useReservation

        protected MapEvent useReservation()
        After having successfully made a reservation, this method completes the reservation process by setting the status to processing for the thread that made the reservation.

        This is an internal method.

        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 and then to have synchronized on this Status object itself, in that explicit order. 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

      • mergeEvents

        protected MapEvent mergeEvents​(MapEvent evtOld,
                               MapEvent evtNew)
        Merge two events that have been raised in sequence from a given map.
        Parameters:
        evtOld - the first event
        evtNew - the second event
        Returns:
        the merged event

      • 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