Class LSpace<K,V>

java.lang.Object
org.jpos.space.LSpace<K,V>
Type Parameters:
K - the key type
V - the value type
All Implemented Interfaces:
AutoCloseable, Runnable, LocalSpace<K,V>, Space<K,V>, Loggeable
public class LSpace<K,V> extends Object implements LocalSpace<K,V>, Loggeable, Runnable
LSpace (Loom-optimized Space) implementation with per-key locking for Virtual Thread efficiency.

This implementation addresses the thundering herd problem in traditional Space implementations by using per-key ReentrantLock and Condition objects instead of global synchronization. With Virtual Threads (Project Loom), this prevents thousands of threads from being unnecessarily woken up when only one is relevant.

Key features:

  • Per-key isolation: Each key has its own lock and condition variables
  • Targeted wakeups: Only threads waiting on a specific key are signaled
  • Virtual Thread optimized: Scales efficiently with thousands of concurrent threads
  • Full LocalSpace compatibility: Drop-in replacement with same API and behavior
  • JFR instrumentation: All operations emit SpaceEvent for monitoring
Concurrency notes (core safety invariants): - Never remove a KeyEntry from entries while threads are waiting on that entry's hasValue Condition, otherwise those waiters can be stranded forever (future out() creates a new KeyEntry+Condition). - Blocking rd()/in() must never return null unless interrupted (or timed out for timed variants).
Since:
3.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    GCDELAY
    GC sweep delay in milliseconds.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LSpace()
    Default constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addListener(Object key, SpaceListener listener)
    add a SpaceListener associated with a given key
    void
    addListener(Object key, SpaceListener listener, long timeout)
    add a SpaceListener associated with a given key for a given period of time.
    void
    close()
    Cancels the periodic GC task so this instance can be garbage-collected.
    void
    dump(PrintStream p, String indent)
    Dumps a human-readable representation of this object to the print stream.
    boolean
    existAny(K[] keys)
    Returns true if any of the given keys are present in the space.
    boolean
    existAny(K[] keys, long timeout)
    Returns true if any of the given keys become available within the timeout.
    void
    gc()
    Runs a garbage-collection sweep to remove expired space entries.
    Map
    getEntries()
    Non-standard method (required for space replication) - use with care.
    String
    getKeysAsString()
    Returns all current keys as a space-separated string.
    Set<K>
    getKeySet()
    Returns the set of all keys currently present in the space.
    V
    in(Object key)
    Take an entry from the space, waiting forever until one exists.
    V
    in(Object key, long timeout)
    Take an entry from the space, waiting a limited amount of time until one exists.
    V
    inp(Object key)
    In probe takes an entry from the space if one exists, return null otherwise.
    boolean
    isEmpty()
    Returns true if this space contains no entries.
    void
    notifyListeners(Object key, Object value)
    Notifies all registered listeners for the given key/value pair.
    void
    nrd(Object key)
    Nrd (not read) waits forever until Key is not present in space.
    Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
    V
    nrd(Object key, long timeout)
    Nrd (not read) waits up to timeout until Key is not present in space.
    Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
    void
    out(K key, V value)
    Write a new entry into the Space
    void
    out(K key, V value, long timeout)
    Write a new entry into the Space, with an timeout value
    void
    push(K key, V value)
    Write a new entry at the head of a queue.
    void
    push(K key, V value, long timeout)
    Write a new entry at the head of the queue with a timeout value
    void
    put(K key, V value)
    Write a single entry at the head of the queue discarding the other entries
    void
    put(K key, V value, long timeout)
    Write a single entry at the head of the queue discarding the other entries, with timeout.
    V
    rd(Object key)
    Read an entry from the space, waiting forever until one exists.
    V
    rd(Object key, long timeout)
    Read an entry from the space, waiting a limited amount of time until one exists.
    V
    rdp(Object key)
    Read probe reads an entry from the space if one exists, return null otherwise.
    void
    removeListener(Object key, SpaceListener listener)
    removes a SpaceListener associated with a given key
    void
    run()
     
    void
    setEntries(Map entries)
    Non-standard method (required for space replication) - use with care.
    int
    size(Object key)
    Returns the number of entries queued under the given key.

    Methods inherited from class Object

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

    Methods inherited from interface Loggeable

    dump
    Modifier and Type
    Method
    Description
    default void
    dump(PrintStream p, String indent, LogRenderer.Type type)
    Dumps a representation of this object using the specified renderer type.

  • Field Details

  • Constructor Details

    • LSpace

      public LSpace()
      Default constructor.

  • Method Details

    • out

      public void out(K key, V value)
      Description copied from interface: Space
      Write a new entry into the Space
      Specified by:
      out in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value

    • out

      public void out(K key, V value, long timeout)
      Description copied from interface: Space
      Write a new entry into the Space, with an timeout value
      Specified by:
      out in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value
      timeout - timeout value in millis

    • push

      public void push(K key, V value)
      Description copied from interface: Space
      Write a new entry at the head of a queue.
      Specified by:
      push in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value

    • push

      public void push(K key, V value, long timeout)
      Description copied from interface: Space
      Write a new entry at the head of the queue with a timeout value
      Specified by:
      push in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value
      timeout - timeout value in millis

    • put

      public void put(K key, V value)
      Description copied from interface: Space
      Write a single entry at the head of the queue discarding the other entries
      Specified by:
      put in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value

    • put

      public void put(K key, V value, long timeout)
      Description copied from interface: Space
      Write a single entry at the head of the queue discarding the other entries, with timeout.
      Specified by:
      put in interface Space<K,V>
      Parameters:
      key - Entry's key
      value - Object value
      timeout - timeout value in millis

    • rdp

      public V rdp(Object key)
      Description copied from interface: Space
      Read probe reads an entry from the space if one exists, return null otherwise.
      Specified by:
      rdp in interface Space<K,V>
      Parameters:
      key - Entry's key
      Returns:
      value or null

    • inp

      public V inp(Object key)
      Description copied from interface: Space
      In probe takes an entry from the space if one exists, return null otherwise.
      Specified by:
      inp in interface Space<K,V>
      Parameters:
      key - Entry's key
      Returns:
      value or null

    • in

      public V in(Object key)
      Description copied from interface: Space
      Take an entry from the space, waiting forever until one exists.
      Specified by:
      in in interface Space<K,V>
      Parameters:
      key - Entry's key
      Returns:
      value

    • in

      public V in(Object key, long timeout)
      Description copied from interface: Space
      Take an entry from the space, waiting a limited amount of time until one exists.
      Specified by:
      in in interface Space<K,V>
      Parameters:
      key - Entry's key
      timeout - millis to wait
      Returns:
      value or null

    • rd

      public V rd(Object key)
      Description copied from interface: Space
      Read an entry from the space, waiting forever until one exists.
      Specified by:
      rd in interface Space<K,V>
      Parameters:
      key - Entry's key
      Returns:
      value

    • rd

      public V rd(Object key, long timeout)
      Description copied from interface: Space
      Read an entry from the space, waiting a limited amount of time until one exists.
      Specified by:
      rd in interface Space<K,V>
      Parameters:
      key - Entry's key
      timeout - millis to wait
      Returns:
      value or null

    • nrd

      public void nrd(Object key)
      Description copied from interface: Space
      Nrd (not read) waits forever until Key is not present in space.
      Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
      Specified by:
      nrd in interface Space<K,V>
      Parameters:
      key - Entry's key

    • nrd

      public V nrd(Object key, long timeout)
      Description copied from interface: Space
      Nrd (not read) waits up to timeout until Key is not present in space.
      Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
      Specified by:
      nrd in interface Space<K,V>
      Parameters:
      key - Entry's key
      timeout - millis to wait
      Returns:
      value or null

    • existAny

      public boolean existAny(K[] keys)
      Description copied from interface: Space
      Returns true if any of the given keys are present in the space.
      Specified by:
      existAny in interface Space<K,V>
      Parameters:
      keys - array of keys to check
      Returns:
      true if one or more keys are available in the space

    • existAny

      public boolean existAny(K[] keys, long timeout)
      Description copied from interface: Space
      Returns true if any of the given keys become available within the timeout.
      Specified by:
      existAny in interface Space<K,V>
      Parameters:
      keys - array of keys to check
      timeout - to wait for any of the entries to become available in millis
      Returns:
      true if one or more keys are available in the space

    • run

      public void run()
      Specified by:
      run in interface Runnable

    • gc

      public void gc()
      Runs a garbage-collection sweep to remove expired space entries.

    • size

      public int size(Object key)
      Description copied from interface: LocalSpace
      Returns the number of entries queued under the given key.
      Specified by:
      size in interface LocalSpace<K,V>
      Parameters:
      key - the key to query
      Returns:
      number of entries in a given key

    • addListener

      public void addListener(Object key, SpaceListener listener)
      Description copied from interface: LocalSpace
      add a SpaceListener associated with a given key
      Specified by:
      addListener in interface LocalSpace<K,V>
      Parameters:
      key - Entry's key
      listener - a SpaceListener

    • addListener

      public void addListener(Object key, SpaceListener listener, long timeout)
      Description copied from interface: LocalSpace
      add a SpaceListener associated with a given key for a given period of time. Warning: not supported by all space implementations.
      Specified by:
      addListener in interface LocalSpace<K,V>
      Parameters:
      key - Entry's key
      listener - a SpaceListener
      timeout - listener registration timeout in millis

    • removeListener

      public void removeListener(Object key, SpaceListener listener)
      Description copied from interface: LocalSpace
      removes a SpaceListener associated with a given key
      Specified by:
      removeListener in interface LocalSpace<K,V>
      Parameters:
      key - Entry's key
      listener - the SpaceListener

    • isEmpty

      public boolean isEmpty()
      Returns true if this space contains no entries.
      Returns:
      true if empty

    • getKeySet

      public Set<K> getKeySet()
      Description copied from interface: LocalSpace
      Returns the set of all keys currently present in the space.
      Specified by:
      getKeySet in interface LocalSpace<K,V>
      Returns:
      Set containing all keys in Space

    • getKeysAsString

      public String getKeysAsString()
      Returns all current keys as a space-separated string.
      Returns:
      space-separated key list

    • dump

      public void dump(PrintStream p, String indent)
      Description copied from interface: Loggeable
      Dumps a human-readable representation of this object to the print stream.
      Specified by:
      dump in interface Loggeable
      Parameters:
      p - the output stream
      indent - indentation prefix

    • notifyListeners

      public void notifyListeners(Object key, Object value)
      Notifies all registered listeners for the given key/value pair.
      Parameters:
      key - the space key
      value - the new value

    • getEntries

      public Map getEntries()
      Non-standard method (required for space replication) - use with care.
      Returns:
      snapshot map of all entries

    • setEntries

      public void setEntries(Map entries)
      Non-standard method (required for space replication) - use with care.
      Parameters:
      entries - the entries map to load into this space

    • close

      public void close()
      Cancels the periodic GC task so this instance can be garbage-collected. Safe to call multiple times.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Space<K,V>