org.threadly.concurrent.event

Class RunnableListenerHelper

java.lang.Object

org.threadly.concurrent.event.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)

Constructor Summary

Constructors

Constructor and Description
RunnableListenerHelper(boolean callListenersOnce) Constructs a new RunnableListenerHelper.

Method Summary

Modifier and Type	Method and 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