Package trclib.robotcore

Class TrcEvent

java.lang.Object

trclib.robotcore.TrcEvent

public class TrcEvent
extends Object

This class implements the TrcEvent. TrcEvent is very important in our event driven asynchronous architecture where things only happen when an event is signaled.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TrcEvent.Callback	This interface is implemented by the caller so that it can be notified when the event is signaled.
private static class	TrcEvent.CallbackEventList
static enum	TrcEvent.EventState	An event has three possible states: - CLEARED: event should be in this state before starting an asynchronous operation.

Field Summary

Fields

Modifier and Type	Field	Description
private TrcEvent.Callback	callback
private Object	callbackContext
private static final HashMap<Thread,TrcEvent.CallbackEventList>	callbackEventListMap
private final AtomicReference<TrcEvent.EventState>	eventState
private final String	instanceName
private static final String	moduleName
static final TrcDbgTrace	staticTracer
final TrcDbgTrace	tracer

Constructor Summary

Constructors

Constructor	Description
TrcEvent(String instanceName)	Constructor: Create an instance of the object.
TrcEvent(String instanceName, TrcEvent.EventState state)	Constructor: Create an instance of the object.

Method Summary

Modifier and Type	Method	Description
void	cancel()	This method cancels an event if it is not already signaled.
void	clear()	This method clears an event.
boolean	isCanceled()	This method checks if the event was canceled.
boolean	isSignaled()	This method checks if the event is signaled.
static void	performEventCallback()	This method is called by a periodic thread in its thread loop to check if any events in the list are signaled or canceled.
static boolean	registerEventCallback()	This method is called by a periodic thread when the thread has just been started and before it enters its thread loop to register for event callback.
void	setCallback(Thread thread, TrcEvent.Callback callback, Object callbackContext)	This method sets a callback handler so that when the event is signaled, the callback handler is called on the same thread as original caller.
void	setCallback(TrcEvent.Callback callback, Object callbackContext)	This method sets a callback handler so that when the event is signaled, the callback handler is called on the same thread as this call.
void	setCallbackContext(Object callbackContext)	This method is called to set the callback context object typically before the event is signaled.
void	signal()	This method signals an event if it is not canceled.
String	toString()	This method returns the instance name.
static boolean	unregisterEventCallback()	This method is called by a periodic thread when the thread has exited its thread loop and before it is terminated to unregister its thread from event callback.

Methods inherited from class java.lang.Object

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

Field Details

moduleName

private static final String moduleName

staticTracer

public static final TrcDbgTrace staticTracer

tracer

public final TrcDbgTrace tracer

instanceName

private final String instanceName

eventState

private final AtomicReference<TrcEvent.EventState> eventState

callbackEventListMap

private static final HashMap<Thread,TrcEvent.CallbackEventList> callbackEventListMap

callback

private TrcEvent.Callback callback

callbackContext

private Object callbackContext

Constructor Details

TrcEvent

public TrcEvent(String instanceName,
 TrcEvent.EventState state)

Constructor: Create an instance of the object.

Parameters:

instanceName - specifies the instance name.

state - specifies the initial state of the event.

TrcEvent

public TrcEvent(String instanceName)

Constructor: Create an instance of the object.

Parameters:

instanceName - specifies the instance name.

Method Details

toString

public String toString()

This method returns the instance name.

Overrides:

toString in class Object

Returns:

instance name.

clear

public void clear()

This method clears an event.

signal

public void signal()

This method signals an event if it is not canceled.

cancel

public void cancel()

This method cancels an event if it is not already signaled. An event is either signaled or canceled by the event source either of which will cause whoever is waiting for it to move on. Note: if an event is canceled, no callback will be performed.

isSignaled

public boolean isSignaled()

This method checks if the event is signaled.

Returns:

true if the event is signaled, false otherwise.

isCanceled

public boolean isCanceled()

This method checks if the event was canceled.

Returns:

true if the event was canceled, false otherwise.

setCallback

public void setCallback(Thread thread,
 TrcEvent.Callback callback,
 Object callbackContext)

This method sets a callback handler so that when the event is signaled, the callback handler is called on the same thread as original caller. This could be very useful if the caller wants to perform some minor actions after an asynchronous operation is completed. Without the callback, the caller would have to set up a state machine waiting for the event to signal, then perform the action. Since the callback is done on the same thread, the caller doesn't have to worry about thread safety. Note: this method is called by another thread on behalf of the original caller.

Parameters:

thread - specifies the thread to do the callback.

callback - specifies the callback handler, null for removing previous callback handler.

callbackContext - specifies the context object passing back to the callback handler.

setCallback

public void setCallback(TrcEvent.Callback callback,
 Object callbackContext)

This method sets a callback handler so that when the event is signaled, the callback handler is called on the same thread as this call. This could be very useful if the caller wants to perform some minor actions after an asynchronous operation is completed. Without the callback, the caller would have to set up a state machine waiting for the event to signal, then perform the action. Since the callback is done on the same thread, the caller doesn't have to worry about thread safety.

Parameters:

callback - specifies the callback handler, null for removing previous callback handler.

callbackContext - specifies the context object passing back to the callback handler.

setCallbackContext

public void setCallbackContext(Object callbackContext)

This method is called to set the callback context object typically before the event is signaled. In some scenarios, the callbackContext is set by the one who's signaling the event, not the one who calls setCallback. Therefore, this method provides a way to do just that.

Parameters:

callbackContext - specifies the callback context object.

registerEventCallback

public static boolean registerEventCallback()

This method is called by a periodic thread when the thread has just been started and before it enters its thread loop to register for event callback. When a callback handler is set for an event, the event is added to the event list for the thread. The periodic thread will then periodically call checkForEventCallback to check if any events in the list are signaled or canceled. When that happens, the callback will be performed and the event will be removed from the event list.

Returns:

true if registration was successful, false if the thread has already registered an event list before.

unregisterEventCallback

public static boolean unregisterEventCallback()

This method is called by a periodic thread when the thread has exited its thread loop and before it is terminated to unregister its thread from event callback.

Returns:

true if unregister is successful, false if the thread was never registered.

performEventCallback

public static void performEventCallback()

This method is called by a periodic thread in its thread loop to check if any events in the list are signaled or canceled. When that happens, it performs the event callback on the periodic thread.