Module net.minestom.server
Package net.minestom.server.thread

Interface Acquirable<T>

@Experimental public sealed interface Acquirable<T>

  • Method Summary

    Modifier and Type
    Method
    Description
    default <R> R
    applySync(Function<T,R> function)
    Locks the acquirable element, execute function synchronously and unlock the thread.
    void
    assertOwnership()
    Checks if the current thread owns the acquirable element.
    @UnknownNullability TickThread
    assignedThread()
    Gets the thread to which this acquirable element is assigned.
    boolean
    isLocal()
    Gets if the acquirable element is local to this thread
    boolean
    isOwned()
    Gets if the acquirable element is owned by this thread.
    default Optional<T>
    local()
    Retrieves the acquirable value if and only if the element is already present/ticked in the current thread.
    static Stream<Entity>
    localEntities()
    Gets all the entities being ticked in the current thread.
    Acquired<T>
    lock()
    Returns a new Acquired object which will be locked to the current thread.
    default Optional<T>
    owned()
    Retrieves the acquirable value if and only if the element is already acquired/owned.
    static long
    resetAcquiringTime()
    Retrieve and reset acquiring time.
    void
    sync(Consumer<T> consumer)
    Locks the acquirable element, execute consumer synchronously and unlock the thread.
    boolean
    trySync(Consumer<T> consumer)
    Try to cheaply lock the acquirable element, execute consumer synchronously and unlock the thread.
    static <T> Acquirable<T>
    unassigned(T value)
    Creates a new Acquirable object.
    T
    unwrap()
    Unwrap the contained object unsafely.

  • Method Details

    • localEntities

      static Stream<Entity> localEntities()
      Gets all the entities being ticked in the current thread.

      Useful when you want to ensure that no acquisition is ever done.

      Be aware that the entity stream is only updated at the beginning of the thread tick.

      Returns:
      the entities ticked in the current thread

    • resetAcquiringTime

      @Internal static long resetAcquiringTime()
      Retrieve and reset acquiring time.

    • unassigned

      @Internal static <T> Acquirable<T> unassigned(T value)
      Creates a new Acquirable object.

      Mostly for internal use, as a TickThread has to be used and properly synchronized.

      Type Parameters:
      T - the acquirable element type
      Parameters:
      value - the acquirable element
      Returns:
      a new acquirable object

    • lock

      Acquired<T> lock()
      Returns a new Acquired object which will be locked to the current thread.

      Useful when your code cannot be done inside a callback and need to be sync. Do not forget to call Acquired.unlock() once you are done with it.

      Returns:
      an acquired object
      Throws:
      IllegalStateException - if the acquirable element is not initialized
      See Also:

    • local

      default Optional<T> local()
      Retrieves the acquirable value if and only if the element is already present/ticked in the current thread.

      Useful when you want only want to acquire an element when you are guaranteed to do not access any external thread.

      Returns:
      an optional containing the acquired element if safe Optional.empty() otherwise

    • isLocal

      boolean isLocal()
      Gets if the acquirable element is local to this thread
      Returns:
      true if the element is linked to the current thread

    • owned

      default Optional<T> owned()
      Retrieves the acquirable value if and only if the element is already acquired/owned.

      Useful when you want only want to acquire an element without depending on any more lock.

      Less strict than local() as using an owned element may create contention.

      Returns:
      an optional containing the acquired element if safe Optional.empty() otherwise

    • isOwned

      boolean isOwned()
      Gets if the acquirable element is owned by this thread. Either by being local, or by already being acquired in the current scope.
      Returns:
      true if the element is linked to the current thread

    • sync

      void sync(Consumer<T> consumer)
      Locks the acquirable element, execute consumer synchronously and unlock the thread.

      Free if the element is already present in the current thread, blocking otherwise.

      Parameters:
      consumer - the callback to execute once the element has been safely acquired

    • trySync

      boolean trySync(Consumer<T> consumer)
      Try to cheaply lock the acquirable element, execute consumer synchronously and unlock the thread.

      Returns false if there is contention.

      Parameters:
      consumer - the callback to execute once the element has been safely acquired
      Returns:
      true if the consumer was executed, false otherwise

    • applySync

      default <R> R applySync(Function<T,R> function)
      Locks the acquirable element, execute function synchronously and unlock the thread.

      Free if the element is already present in the current thread, blocking otherwise.

      Parameters:
      function - the function to execute once the element has been safely acquired

    • unwrap

      T unwrap()
      Unwrap the contained object unsafely.

      Should only be considered when thread-safety is not necessary (e.g. comparing positions)

      Returns:
      the unwrapped value

    • assignedThread

      @UnknownNullability TickThread assignedThread()
      Gets the thread to which this acquirable element is assigned.

      May change to one tick to the next.

      Returns:
      the assigned thread, null if not initialized (likely on the next tick)

    • assertOwnership

      void assertOwnership()
      Checks if the current thread owns the acquirable element.

      Throws an AcquirableOwnershipException if not owned.

      This method is only enabled when assertions are enabled or ServerFlag.ACQUIRABLE_STRICT is set to true.

      Throws:
      AcquirableOwnershipException - if the current thread does not own the acquirable element