E - The type of SimEvents supported.public interface SimEventList<E extends SimEvent> extends SortedSet<E>, Runnable
SimEvents.
Since a SortedSet is being used for bookkeeping of the events, the
events themselves must be totally ordered.
During its life, an event list always has a notion of "current time", see getTime().
Upon creation of the event list,
the time is set to the so-called default reset time,
see getDefaultResetTime().
The latter should default to Double.NEGATIVE_INFINITY,
but can be set through setDefaultResetTime(double).
In addition, implementations are strongly encouraged to provide constructors
capable of setting the default reset time at creation time of the event list.
The time is only updated as a result of running the event list (e.g, in run()),
during which time is non-decreasing.
The process of running an event list is simply to repeatedly remove the first element of the underlying SortedSet,
until the set is empty (or until another termination criterion is met before that).
This means you can for instance schedule new events from within the context of execution of
an event. However, all events scheduled this way must not be in the past.
This is rigorously checked for! If the event list discovers the insertion of new SimEvents in the past,
it will throw an exception!
An event-list instance can be reused by resetting it, which is done through reset(double),
after which the list is empty and time is getDefaultResetTime().
It is also possible to reset to a specific time (still clearing the event list, though)
through reset(double).
Obviously, resetting should not be done while processing the event list (e.g., this should
probably not be done from within an event action), as this will result in the list throwing an exception (noting time is no
longer non-decreasing).
In between event-list runs (run()), the event list can be safely added to and removed from. While running the list,
events can be added and removed at will, as long as no events are added that are in the past. The list will throw an exception
when noting this. Adding events with time equal to the current time is always safe though; such events will always be
executed after the current event (though other events may precede in between!).
Note that events that have the same time, may not be processed in insertion order! It is up to the implementation whether to specify whether it guarantees insertion order or some other criterion. However, between events scheduled at the same time, the order of execution itself is fixed as long as these events are present (and are not rescheduled). This implies that upon insertion of an event having the same time as an event already present, their relative order is determined immediately (yet, this may not be insertion order).
While running, the event-list maintains the notion of updates, being "jumps in time". So, as long as the list processes events with equal times, it does not fire such an update. The concept of updates is very useful for statistics, in particular, for integration/averaging, since these operations require non-trivial time steps for updates. Note that irrespective of its time, the first event processed after creation of the event list or after a reset always fires an update.
A SimEventList supports various notification mechanisms to registered listeners.
When and with what detail listeners are notified of changes to the event list depends on the actual listener type,
see SimEventListResetListener, SimEventListListener and SimEventListListener.Fine.
An event list is really meant to be processed and operated upon by a single thread only.
A SimEventList must be capable of generating suitable SimEvents itself,
for instance for scheduling user-provided SimEventActions at a specific time.
The preferred way of achieving this is through setting a factory method,
see getSimEventFactory() and setSimEventFactory(org.javades.jsimulation.r5.SimEventFactory<? extends E>).
Note that the factory may be absent,
because we do not want to burden our users with its mandatory registration.
When the event factory is absent,
the SimEvent class (as provided through the <E> type parameter
and its runtime companion getSimEventClass())
must support a parameterless constructor.
Last javadoc Review: Jan de Jongh, TNO, 20180404, r5.1.0.
DefaultSimEventComparator,
SimEvent| Modifier and Type | Method and Description |
|---|---|
void |
addListener(SimEventListResetListener l)
Adds a listener to this event list.
|
double |
getDefaultResetTime()
Gets the default reset time, the time on the event list after it is reset (without explicit time argument).
|
Class<E> |
getSimEventClass()
|
SimEventFactory<? extends E> |
getSimEventFactory()
Gets the factory for
SimEvents created by this SimEventList. |
double |
getTime()
Returns the current time during processing of the event list.
|
default void |
print()
Prints a representation of this event list on
System.out. |
default void |
print(PrintStream stream)
Prints a representation of this event list on given stream.
|
void |
removeListener(SimEventListResetListener l)
Removes a listener from this event list.
|
default void |
reschedule(double time,
E event)
Reschedules an event on this list, at given time (overriding the time set on the event itself).
|
default void |
reset()
Resets the event list.
|
void |
reset(double time)
Resets the event list to a specific time.
|
default void |
run()
Runs the event list until it is empty (or until interrupted).
|
void |
runSingleStep()
Runs a single (the first) event from the event list ("single-stepping").
|
void |
runUntil(double endTime,
boolean inclusive,
boolean setTimeToEndTime)
Runs the event list until it is empty, interrupted, or until a specific point in time has been reached.
|
default void |
schedule(double time,
E event)
Schedules an event on this list, at given time (overriding the time set on the event itself).
|
default E |
schedule(double time,
SimEventAction action)
Schedules an action at given time.
|
default E |
schedule(double time,
SimEventAction action,
String name)
Schedules an action at given time.
|
default void |
schedule(E event)
Schedules an event on this list, taking the schedule time from the event itself.
|
default void |
scheduleNow(E event)
Schedules an event on this list at current time (overriding the time set on the event itself).
|
default E |
scheduleNow(SimEventAction action)
Schedules an action now.
|
default E |
scheduleNow(SimEventAction action,
String name)
Schedules an action now.
|
void |
setDefaultResetTime(double defaultResetTime)
Sets the default reset time, the time on the event list after it is reset (without explicit time argument).
|
void |
setSimEventFactory(SimEventFactory<? extends E> eventFactory)
Sets the factory for
SimEvents created by this SimEventList. |
comparator, first, headSet, last, spliterator, subSet, tailSetadd, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArrayparallelStream, removeIf, streamdefault void print()
System.out.default void print(PrintStream stream)
stream - The stream to which to print; if null, System.out is used.double getDefaultResetTime()
The default value (i.e., the default reset time if not set explicitly through setDefaultResetTime(double))
is negative infinity.
reset(),
reset(double)void setDefaultResetTime(double defaultResetTime)
The value supplied (obviously) survives resets;
the last value set through this method is only
used by reset().
This method can be called at any time; the default reset time is only used while actually performing a reset.
defaultResetTime - The new default reset time (minus and positive infinity are allowed).reset(),
reset(double)double getTime()
SimEventFactory<? extends E> getSimEventFactory()
SimEvents created by this SimEventList.null.void setSimEventFactory(SimEventFactory<? extends E> eventFactory)
SimEvents created by this SimEventList.eventFactory - The event factory; may be null to stop using it.void reset(double time)
Removes all events, and sets time to the given value. An exception is thrown if the event list is currently running.
This method ignores the default reset time, as given by getDefaultResetTime(),
but does not change that value.
time - The new time of the event list.IllegalStateException - If the event list is currently running.run()default void reset()
Removes all events, and sets time to getDefaultResetTime().
An exception is thrown if the event list is currently running.
IllegalStateException - If the event list is currently running.run(),
getDefaultResetTime(),
setDefaultResetTime(double)void runUntil(double endTime,
boolean inclusive,
boolean setTimeToEndTime)
After returning from this method, it can be invoked later, but the end time passed must not decrease in this sequence.
See also reset(double).
Optionally, but only if inclusive == true, the time on the event list is increased to the endTime
argument.
Otherwise, not that the current time on the event list may be smaller than the end time provided!
endTime - The time until which to run the event list.inclusive - Whether to include events at the end time parameter.setTimeToEndTime - Whether to increase the current time to the end time given after processing the applicable events
(ignored if inclusive == false).IllegalStateException - If the method is invoked recursively (or from another thread before finishing).IllegalArgumentException - If endTime is in the past.getTime(),
SimEvent.getTime(),
run()default void run()
This method leaves the time to that of the last event processed.
run in interface RunnableIllegalStateException - If the method is invoked recursively (or from another thread before finishing).runUntil(double, boolean, boolean)void runSingleStep()
void addListener(SimEventListResetListener l)
l - The listener to be added, ignored if null.void removeListener(SimEventListResetListener l)
l - The listener to be removed, ignored if null or not present.default void schedule(E event)
event - The event to schedule.IllegalArgumentException - If the event is null, has a schedule time in the past, or
is already scheduled.getTime(),
SimEvent.getTime()default void schedule(double time,
E event)
The time on the SimEvent argument is overwritten.
time - The schedule time for the event.event - The event to schedule.IllegalArgumentException - If the event is null or already scheduled,
or the schedule time is in the past.SimEvent.setTime(double),
getTime()default void reschedule(double time,
E event)
The time on the SimEvent argument is overwritten.
This method reinserts the event (after setting the new time on it) into the event list.
If the event is not present in the list, the effects of this method are identical to those of
schedule(double, SimEvent).
time - The (new) schedule time for the event.event - The event to (re)schedule.IllegalArgumentException - If the event is null,
or the new schedule time is in the past.SimEvent.setTime(double),
getTime()default E schedule(double time, SimEventAction action, String name)
Note that if the action argument is null,
a SimEvent is still created and scheduled
with null SimEventAction.
This method (and all others instantiating SimEvents)
uses a non-null SimEventFactory
if available through getSimEventFactory().
Otherwise,
it attempts to find and invoke a null constructor
on getSimEventClass() (which fails if that is an interface).
time - The schedule time for the action.action - The action to schedule, may be null.name - The name for the event, may be null.IllegalArgumentException - If the schedule time is the past.IllegalStateException - If a new SimEvent could not be instantiated.default E schedule(double time, SimEventAction action)
Note that if the action argument is null,
a SimEvent is still created and scheduled
with null SimEventAction.
time - The schedule time for the action.action - The action to schedule, may be null.IllegalArgumentException - If the schedule time is the past.IllegalStateException - If a new SimEvent could not be instantiated.default void scheduleNow(E event)
The time on the SimEvent argument is overwritten.
There is no guarantee that the new scheduled event will be the next event to be executed.
Note that it is legal to reschedule the event currently being executed from within its SimEvent.getEventAction(),
even at the same time (in which case the action is invoked again, with the same time argument).
event - The event to schedule.IllegalArgumentException - If the event is null or already scheduled.SimEvent.setTime(double),
getTime()default E scheduleNow(SimEventAction action, String name)
Note that if the action argument is null,
a SimEvent is still created and scheduled
with null SimEventAction.
There is no guarantee that the new scheduled event will be the next event to be executed.
action - The action to schedule, may be null.name - The name for the event, may be null.IllegalStateException - If a new SimEvent could not be instantiated.default E scheduleNow(SimEventAction action)
Note that if the action argument is null,
a SimEvent is still created and scheduled
with null SimEventAction.
There is no guarantee that the new scheduled event will be the next event to be executed.
action - The action to schedule, may be null.IllegalStateException - If a new SimEvent could not be instantiated.Copyright © 2018. All rights reserved.