ss: Add javadoc to StateSystem#waitUntilBuilt(long)

If the timeout specified less or equal to 0, then there will no waiting and
this can be used as a "isBuilt" method for the state system.

Change-Id: I6110622071249cd456801fc220500740ba72d6b4
Signed-off-by: Geneviève Bastien <gbastien+lttng@versatic.net>
Reviewed-on: https://git.eclipse.org/r/90309
Reviewed-by: Hudson CI
Reviewed-by: Matthew Khouzam <matthew.khouzam@ericsson.com>
Tested-by: Matthew Khouzam <matthew.khouzam@ericsson.com>
Reviewed-by: Alexandre Montplaisir <alexmonthy@efficios.com>

diff --git a/statesystem/org.eclipse.tracecompass.statesystem.core.tests/src/org/eclipse/tracecompass/statesystem/core/tests/StateSystemTest.java b/statesystem/org.eclipse.tracecompass.statesystem.core.tests/src/org/eclipse/tracecompass/statesystem/core/tests/StateSystemTest.java
new file mode 100644 (file)
index 0000000..8741844
--- /dev/null
+++ b/statesystem/org.eclipse.tracecompass.statesystem.core.tests/src/org/eclipse/tracecompass/statesystem/core/tests/StateSystemTest.java
@@ -0,0 +1,82 @@
+/*******************************************************************************
+ * Copyright (c) 2017 École Polytechnique de Montréal
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.statesystem.core.tests;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import java.util.concurrent.TimeUnit;
+
+import org.eclipse.tracecompass.internal.statesystem.core.StateSystem;
+import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
+import org.eclipse.tracecompass.statesystem.core.backend.IStateHistoryBackend;
+import org.eclipse.tracecompass.statesystem.core.backend.StateHistoryBackendFactory;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TestRule;
+import org.junit.rules.Timeout;
+
+/**
+ * Test the {@link StateSystem} specific methods
+ *
+ * @author Geneviève Bastien
+ */
+public class StateSystemTest {
+
+    /** Time-out tests after 1 minute. */
+    @Rule
+    public TestRule globalTimeout = new Timeout(1, TimeUnit.MINUTES);
+
+    private ITmfStateSystemBuilder fSs;
+
+    /**
+     * Create the test state system
+     */
+    @Before
+    public void setup() {
+        IStateHistoryBackend backend = StateHistoryBackendFactory.createNullBackend("Test");
+        fSs = new StateSystem(backend);
+    }
+
+    /**
+     * Test the {@link StateSystem#waitUntilBuilt(long)} method
+     */
+    @Test
+    public void testWaitUntilBuilt() {
+        ITmfStateSystemBuilder ss = fSs;
+        assertNotNull(ss);
+
+        long timeout = 500;
+        long begin = System.currentTimeMillis();
+        assertFalse(ss.waitUntilBuilt(timeout));
+        long end = System.currentTimeMillis();
+
+        /*
+         * We cannot be sure of the exact time, but just make sure the method
+         * returned and the delay is longer than the timeout
+         */
+        assertTrue(end - begin >= timeout);
+
+        /*
+         * The delay is undeterministic, we cannot check anything else than
+         * whether it returned or not
+         */
+        assertFalse(ss.waitUntilBuilt(0));
+
+        ss.closeHistory(timeout);
+
+        /* The history is closed, so now these methods should return true */
+        assertTrue(ss.waitUntilBuilt(timeout));
+        assertTrue(ss.waitUntilBuilt(0));
+    }
+
+}

diff --git a/statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystem.java b/statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystem.java
index 4df70c16192068ce1d1b583dda7dab8fc9bd3867..b9e00992477e8cb50200760a12fcaeae3c4d9f77 100644 (file)
--- a/statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystem.java
+++ b/statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystem.java
@@ -97,6 +97,9 @@ public interface ITmfStateSystem {
      * This can be useful, for example, for a component doing queries
      * periodically to the system while it is being built.
      *
+     * Specifying a timeout of 0 (or less) will return immediately with whether
+     * the state system is finished building or not.
+     *
      * @param timeout
      *            Timeout value in milliseconds
      * @return True if the return was due to the construction finishing, false