Package org.threadly.concurrent.event

Class RunnableListenerHelper

  • Direct Known Subclasses:
    AsyncCallRunnableListenerHelper, DefaultExecutorRunnableListenerHelper
    public class RunnableListenerHelper
extends java.lang.Object
    Class which assist with holding and calling to Runnable listeners. In parallel designs it is common to have things subscribe for actions to occur (to later be alerted once an action occurs). This class makes it easy to allow things to register as a listener.

    For listener designs which are not using runnables, look at ListenerHelper. ListenerHelper allows you to create similar designs while using any any interface to call back on.

    Since:
    2.2.0 (since 1.1.0 as org.threadly.concurrent.ListenerHelper)

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListener​(java.lang.Runnable listener)
      Adds a listener to be called.
      void addListener​(java.lang.Runnable listener, java.util.concurrent.Executor executor)
      Adds a listener to be called.
      void addListener​(java.lang.Runnable listener, java.util.concurrent.Executor queueExecutor, java.util.concurrent.Executor inThreadExecutionExecutor)
      Adds a listener to be called.
      void callListeners()
      Will call all listeners that are registered with this helper.
      void clearListeners()
      Removes all listeners currently registered.
      java.util.Collection<java.lang.Runnable> getSubscribedListeners()
      Return a collection of the currently subscribed listener instances.
      int registeredListenerCount()
      Returns how many listeners were added, and will be ran on the next call to callListeners.
      boolean removeListener​(java.lang.Runnable listener)
      Attempts to remove a listener waiting to be called.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • RunnableListenerHelper

        public RunnableListenerHelper​(boolean callListenersOnce)
        Constructs a new RunnableListenerHelper. This can call listeners only once, or every time callListeners() is called.
        Parameters:
        callListenersOnce - true if listeners should only be called once

    • Method Detail

      • getSubscribedListeners

        public java.util.Collection<java.lang.Runnable> getSubscribedListeners()
        Return a collection of the currently subscribed listener instances. This returned collection can NOT be modified.
        Returns:
        A non-null collection of currently subscribed listeners

      • callListeners

        public void callListeners()
        Will call all listeners that are registered with this helper. If any listeners were provided without an executor, they will execute in the calling thread. No exceptions will be thrown in this calling thread if any exceptions occur from the listeners.

        If calling multiple times, this will only have an effect if constructed with a false, indicating that listeners can expect to be called multiple times. In which case all listeners that have registered will be called again. If this was constructed with the expectation of only calling once an IllegalStateException will be thrown on subsequent calls.

      • addListener

        public void addListener​(java.lang.Runnable listener)
        Adds a listener to be called. If the RunnableListenerHelper was constructed with true (listeners can only be called once) then this listener will be called immediately. This just defers to the other addListener call, providing null for the executor. So when the listener runs, it will be on the same thread as the one invoking callListeners().
        Parameters:
        listener - runnable to call when trigger event called

      • addListener

        public void addListener​(java.lang.Runnable listener,
                        java.util.concurrent.Executor executor)
        Adds a listener to be called. If the RunnableListenerHelper was constructed with true (listeners can only be called once) then this listener will be called immediately. If the executor is null it will be called either on this thread or the thread calling callListeners() (depending on the previous condition).

        If an Executor is provided, and that Executor is NOT single threaded, the listener may be called concurrently. You can ensure this wont happen by using the KeyDistributedExecutor to get an executor from a single key, or by using the ExecutorLimiter with a limit of one, or an instance of the SingleThreadScheduler.

        Parameters:
        listener - runnable to call when trigger event called
        executor - executor listener should run on, or null

      • addListener

        public void addListener​(java.lang.Runnable listener,
                        java.util.concurrent.Executor queueExecutor,
                        java.util.concurrent.Executor inThreadExecutionExecutor)
        Adds a listener to be called. If the RunnableListenerHelper was constructed with true (listeners can only be called once) then this listener will be called immediately.

        This allows you to provide different executors to use depending on the state of this RunnableListenerHelper. This is typically used as an optimization inside the threadly library only. Most users will be looking for the addListener(Runnable, Executor) which just provides that executor to both arguments here.

        Parameters:
        listener - runnable to call when trigger event called
        queueExecutor - executor listener should run on if this has to queue, or null
        inThreadExecutionExecutor - executor listener should run on if this helpers state has transitioned to done

      • removeListener

        public boolean removeListener​(java.lang.Runnable listener)
        Attempts to remove a listener waiting to be called.
        Parameters:
        listener - listener instance to be removed
        Returns:
        true if the listener was removed

      • clearListeners

        public void clearListeners()
        Removes all listeners currently registered.

      • registeredListenerCount

        public int registeredListenerCount()
        Returns how many listeners were added, and will be ran on the next call to callListeners. If this was constructed to only run once, all listeners will be removed after called, and thus this will report zero after callListeners has been invoked.
        Returns:
        number of listeners registered to be called