Class Signal<T>

java.lang.Object
me.tamkungz.signals.Signal<T>
Type Parameters:
T - event payload type
public final class Signal<T> extends Object
Lightweight signal facade for a single payload type.

A signal is a view of one channel on a SignalBus: every Signal created for the same SignalKey shares the same listeners.

  • Method Details

    • bus

      public SignalBus bus()
      Returns the bus this signal lives on.
      Returns:
      the signal bus

    • key

      public SignalKey<T> key()
      Returns the key of this signal's channel.
      Returns:
      the signal key

    • eventType

      public Class<T> eventType()
      Returns the payload type of this signal.
      Returns:
      payload class

    • connect

      public Connection connect(Consumer<T> listener)
      Connects a listener.
      Parameters:
      listener - listener to call for every value
      Returns:
      the connection for this listener

    • connect

      public Connection connect(ConnectionGroup group, Consumer<T> listener)
      Connects a listener and tracks it in a group.
      Parameters:
      group - group that will disconnect the listener
      listener - listener to call for every value
      Returns:
      the connection for this listener

    • connectIf

      public Connection connectIf(Predicate<T> predicate, Consumer<T> listener)
      Connects a listener that only receives the values a predicate accepts.
      Parameters:
      predicate - decides which values reach the listener
      listener - listener to call for accepted values
      Returns:
      the connection for this listener

    • connectIf

      public Connection connectIf(ConnectionGroup group, Predicate<T> predicate, Consumer<T> listener)
      Connects a filtered listener and tracks it in a group.
      Parameters:
      group - group that will disconnect the listener
      predicate - decides which values reach the listener
      listener - listener to call for accepted values
      Returns:
      the connection for this listener

    • connectOn

      public Connection connectOn(Executor executor, Consumer<T> listener)
      Connects a listener that runs on an executor instead of on the thread that fires the signal.

      Every value is handed to the executor as a task, so a listener can hop to the thread it needs, for example the server's main thread. Values are delivered in the order the executor runs the tasks. A task that is still queued when the connection is disconnected is skipped.

      Whatever the listener does happens after fire(T) has returned, so it cannot change an event the firing code is still waiting on (cancel it, change its message, ...). If the executor throws while accepting a task, the exception is treated like one thrown by any other listener. Exceptions from the listener itself are handled by the executor, not by the bus.

      Parameters:
      executor - executor that runs the listener
      listener - listener to call for every value
      Returns:
      the connection for this listener

    • connectOn

      public Connection connectOn(ConnectionGroup group, Executor executor, Consumer<T> listener)
      Connects a listener that runs on an executor and tracks it in a group.
      Parameters:
      group - group that will disconnect the listener
      executor - executor that runs the listener
      listener - listener to call for every value
      Returns:
      the connection for this listener
      See Also:

    • once

      public Connection once(Consumer<T> listener)
      Connects a listener that is disconnected after its first value.
      Parameters:
      listener - listener to call at most once
      Returns:
      the connection for this listener

    • once

      public Connection once(ConnectionGroup group, Consumer<T> listener)
      Connects a one-shot listener and tracks it in a group.
      Parameters:
      group - group that will disconnect the listener
      listener - listener to call at most once
      Returns:
      the connection for this listener

    • next

      public CompletableFuture<T> next()
      Returns a future that completes with the next value of this signal.

      The listener behind it disconnects as soon as the future completes. Cancelling the future disconnects it too, so a future nobody waits for any more does not stay connected.

      The future is completed on the thread that fires the signal, and so are the stages you chain with the non-Async methods (thenAccept and friends). When that thread matters (an async chat event, a region thread on Folia), use the Async variants with the executor you need.

      Returns:
      a future for the next value

    • next

      public CompletableFuture<T> next(Predicate<T> predicate)
      Returns a future that completes with the next value of this signal that a predicate accepts.

      If the predicate throws, the future completes exceptionally with that exception instead of the exception reaching the code that fires the signal. See next() for disconnecting and for the thread the future completes on.

      Parameters:
      predicate - decides which value completes the future
      Returns:
      a future for the first accepted value

    • filter

      public Signal<T> filter(Predicate<T> predicate)
      Returns a new signal that only carries the values a predicate accepts.

      The new signal has its own channel; firing on it does not loop back into this signal. Clearing it also detaches it from this signal.

      Parameters:
      predicate - decides which values pass
      Returns:
      a derived signal of the same payload type

    • map

      public <R> Signal<R> map(Class<R> resultType, Function<T,R> mapper)
      Returns a new signal that carries every value of this signal converted by a function.

      The new signal has its own channel. Clearing it also detaches it from this signal.

      Type Parameters:
      R - payload type of the new signal
      Parameters:
      resultType - payload type of the new signal
      mapper - converts a value of this signal
      Returns:
      a derived signal of the result type

    • fire

      public void fire(T value)
      Delivers a value to every listener of this signal, on the calling thread.
      Parameters:
      value - value to deliver

    • listenerCount

      public int listenerCount()
      Counts the listeners connected to this signal's channel.
      Returns:
      number of connected listeners

    • hasReceivers

      public boolean hasReceivers()
      Tells whether a value fired on this signal could reach anything: a listener on its channel, or a sub-bus of its bus.
      Returns:
      false only if firing could not reach any listener
      See Also:

    • clear

      public void clear()
      Disconnects every listener of this signal's channel, including ones connected through other Signal instances for the same key. For a signal made by filter(Predicate) or map(Class, Function) it also detaches the signal from its source.