BitDisplay, ManualSwitch now Observable. More Docs added in Timeline.

[Mograsim.git] / net.mograsim.logic.core / src / net / mograsim / logic / core / timeline / Timeline.java

diff --git a/net.mograsim.logic.core/src/net/mograsim/logic/core/timeline/Timeline.java b/net.mograsim.logic.core/src/net/mograsim/logic/core/timeline/Timeline.java
index 80a65f4..d578f2c 100644 (file)
--- a/net.mograsim.logic.core/src/net/mograsim/logic/core/timeline/Timeline.java
+++ b/net.mograsim.logic.core/src/net/mograsim/logic/core/timeline/Timeline.java
@@ -21,23 +21,33 @@ public class Timeline
 \r
        private final List<Consumer<TimelineEvent>> eventAddedListener;\r
 \r
+       public final LongSupplier stepByStepExec = () -> lastTimeUpdated;\r
+       public final LongSupplier realTimeExec = () -> System.currentTimeMillis();\r
+\r
+       /**\r
+        * Constructs a Timeline object. Per default the time function is set to step by step execution.\r
+        * \r
+        * @param initCapacity The initial capacity of the event queue.\r
+        */\r
        public Timeline(int initCapacity)\r
        {\r
                events = new PriorityQueue<>(initCapacity);\r
-\r
                eventAddedListener = new ArrayList<>();\r
-               time = () -> lastTimeUpdated;\r
+               time = stepByStepExec;\r
        }\r
 \r
        /**\r
         * @param timestamp exclusive\r
-        * @return true if the first event is later than the timestamp\r
+        * @return <code>true</code> if the first event in queue is later than the given timestamp\r
         */\r
        public BooleanSupplier laterThan(long timestamp)\r
        {\r
                return () -> timeCmp(events.peek().getTiming(), timestamp) > 0;\r
        }\r
 \r
+       /**\r
+        * @return <code>true</code> if there is at least one event enqueued. <code>false</code> otherwise\r
+        */\r
        public boolean hasNext()\r
        {\r
                return !events.isEmpty();\r
@@ -53,6 +63,9 @@ public class Timeline
                        executeUntil(laterThan(first.getTiming()), -1);\r
        }\r
 \r
+       /**\r
+        * Executes all events enqueued in the {@link Timeline}. Use very carefully! Events may generate new events, causing an infinite loop.\r
+        */\r
        public void executeAll()\r
        {\r
                while (hasNext())\r
@@ -71,7 +84,6 @@ public class Timeline
         * <code>EXEC_UNTIL_CONDITION</code> if the condition was met\r
         * <code>EXEC_UNTIL_EMPTY</code> if events were executed until the {@link Timeline} was empty\r
         * @formatter:on\r
-        * @author Christian Femers, Fabian Stemmler\r
         */\r
        public ExecutionResult executeUntil(BooleanSupplier condition, long stopMillis)\r
        {\r
@@ -97,16 +109,31 @@ public class Timeline
                return hasNext() ? ExecutionResult.EXEC_UNTIL_EMPTY : ExecutionResult.EXEC_UNTIL_CONDITION;\r
        }\r
 \r
+       /**\r
+        * Sets the function, which defines the current simulation time at any time.\r
+        * \r
+        * @param time The return value of calling this function is the current simulation time.\r
+        */\r
        public void setTimeFunction(LongSupplier time)\r
        {\r
                this.time = time;\r
        }\r
 \r
+       /**\r
+        * Calculates the current simulation time.\r
+        * \r
+        * @return The simulation time as defined by the time function.\r
+        */\r
        public long getSimulationTime()\r
        {\r
                return time.getAsLong();\r
        }\r
 \r
+       /**\r
+        * Retrieves the timestamp of the next event.\r
+        * \r
+        * @return The timestamp of the next enqueued event, if the {@link Timeline} is not empty, -1 otherwise.\r
+        */\r
        public long nextEventTime()\r
        {\r
                if (!hasNext())\r
@@ -114,17 +141,26 @@ public class Timeline
                return events.peek().getTiming();\r
        }\r
 \r
+       /**\r
+        * Clears the {@link Timeline} of enqueued events.\r
+        */\r
        public void reset()\r
        {\r
                events.clear();\r
                lastTimeUpdated = 0;\r
        }\r
 \r
+       /**\r
+        * Adds a listener, that is called when a {@link TimelineEvent} is added.\r
+        */\r
        public void addEventAddedListener(Consumer<TimelineEvent> listener)\r
        {\r
                eventAddedListener.add(listener);\r
        }\r
 \r
+       /**\r
+        * Removes the listener, if possible. It will no longer be called when a {@link TimelineEvent} is added.\r
+        */\r
        public void removeEventAddedListener(Consumer<TimelineEvent> listener)\r
        {\r
                eventAddedListener.remove(listener);\r
@@ -185,7 +221,7 @@ public class Timeline
                }\r
        }\r
 \r
-       public static int timeCmp(long a, long b)\r
+       static int timeCmp(long a, long b)\r
        {\r
                return Long.signum(a - b);\r
        }\r