From 7ee77637273e2e913cf19f078e9143ae6977f44f Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Fri, 20 Jun 2025 19:25:10 +0300 Subject: Add comprehensive Javadoc documentation for public APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document core classes: VSTask, VSMessage, VSInternalProcess - Document event interfaces: VSAbstractEvent, VSCopyableEvent, VSTime - Document timestamp events: VSTimestampTriggeredEvent, VSLamportTimestampEvent - Document protocol framework: VSAbstractProtocol methods - Document VSSimulator and VSRegisteredEvents - Add detailed method descriptions with parameter and return value docs - Include usage examples and cross-references between related classes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- src/main/java/core/VSInternalProcess.java | 133 ++++++++++++++++++++++++------ 1 file changed, 107 insertions(+), 26 deletions(-) (limited to 'src/main/java/core/VSInternalProcess.java') diff --git a/src/main/java/core/VSInternalProcess.java b/src/main/java/core/VSInternalProcess.java index 5442cd1..ddf378e 100644 --- a/src/main/java/core/VSInternalProcess.java +++ b/src/main/java/core/VSInternalProcess.java @@ -14,9 +14,24 @@ import simulator.VSSimulatorVisualization; import utils.VSPriorityQueue; /** - * The class VSInternalProcess, an object of this class represents a process - * of a simulator. + * Internal process implementation for the distributed systems simulator. + * This class extends {@link VSAbstractProcess} with simulation-specific features + * including: + * + * + *

Each process maintains its own local time that drifts from global time + * based on configured clock variance, simulating realistic clock skew in + * distributed systems.

* + * @see VSAbstractProcess + * @see VSSimulatorVisualization * @author Paul C. Buetow */ public class VSInternalProcess extends VSAbstractProcess { @@ -39,8 +54,17 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Called from the VSProcessEditor, after finishing editing! This makes - * sure that the VSInternalProcess object is using the up to date prefs! + * Updates this process's configuration from its preference settings. + * Called by {@link simulator.VSProcessEditor} after editing is complete + * to apply any configuration changes. + * + *

This method updates:

+ * */ public synchronized void updateFromPrefs() { setClockVariance(getFloat("process.clock.variance")); @@ -50,8 +74,15 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Called from the VSProcessEditor, before starting editing! This makes - * sure that the editor edits the up to date prefs of the process! + * Saves this process's current state to its preference settings. + * Called by {@link simulator.VSProcessEditor} before editing begins + * to ensure the editor shows current values. + * + *

This method saves:

+ * */ public synchronized void updatePrefs() { setFloat("process.clock.variance", getClockVariance()); @@ -59,12 +90,22 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Syncs the process' time. This method is using the clockOffset and - * clockVariance variables. This method is called repeatedly from the - * VSSimulatorVisualization in order to update the process' local and global - * time values. + * Synchronizes this process's time with the global simulation time. + * This method simulates realistic clock drift using the configured + * clock variance. + * + *

The synchronization algorithm:

+ *
    + *
  1. Calculates time elapsed since last sync
    2. + *
  2. Advances local time by elapsed time
    3. + *
  3. Applies clock drift based on variance
    4. + *
  4. Accumulates fractional time in clockOffset
    5. + *
  5. Ensures time never goes negative
    6. + *
+ * + *

Called repeatedly by {@link VSSimulatorVisualization} during simulation.

* - * @param globalTime the global time. + * @param globalTime the current global simulation time */ public synchronized void syncTime(final long globalTime) { final long currentGlobalTimestep = globalTime - this.globalTime; @@ -89,7 +130,11 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Highlights the process. + * Activates visual highlighting for this process. + * The process's current color is saved and replaced with the highlight color. + * Use {@link #highlightOff()} to restore the original color. + * + * @see #highlightOff() */ public synchronized void highlightOn() { tmpColor = currentColor; @@ -159,28 +204,47 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Creates a random percentage 0..100 using the process' own pseudo - * random number generator object of the VSRandom class. + * Generates a random percentage value between 0 and 100 (inclusive). + * Uses this process's dedicated random number generator to ensure + * reproducible results for a given random seed. + * + *

This method is commonly used for:

+ * * - * @return A random percentage 0..100. + * @return a random integer between 0 and 100 inclusive + * @see utils.VSRandom */ public synchronized int getRandomPercentage() { return random.nextInt() % constants.VSConstants.PERCENTAGE_RANGE; } /** - * Adds the clock offset. This method is used by the task manager. The - * clock offset identifies if the local time of the process has changed and - * how much.. + * Adds to this process's clock offset, adjusting its local time drift. + * Used by the task manager when tasks modify process time. + * + *

The clock offset accumulates fractional time units that are + * converted to whole time units during {@link #syncTime(long)}.

* - * @param add the clock offset to add. + * @param add the amount to add to the clock offset (can be negative) + * @see VSTaskManager#runTasks(long) */ public synchronized void addClockOffset(long add) { this.clockOffset += add; } /** - * The process' state is 'play'. Called by the simulator canvas. + * Transitions this process to the 'playing' state. + * The process resumes normal operation and its color changes + * to indicate running status. + * + *

Called by the simulator when starting or resuming simulation.

+ * + * @see #pause() + * @see #finish() */ public synchronized void play() { isPaused = false; @@ -188,7 +252,14 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * The process' state is 'pause'. Called by the simulator canvas. + * Transitions this process to the 'paused' state. + * The process stops executing and its color changes + * to indicate stopped status. + * + *

Called by the simulator when pausing simulation.

+ * + * @see #play() + * @see #finish() */ public synchronized void pause() { isPaused = true; @@ -196,7 +267,13 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * The process' state is 'Finish'. Called by the simulator canvas. + * Transitions this process to the 'finished' state. + * The process stops executing and returns to its default color. + * + *

Called by the simulator when ending simulation.

+ * + * @see #play() + * @see #pause() */ public synchronized void finish() { isPaused = true; @@ -222,11 +299,15 @@ public class VSInternalProcess extends VSAbstractProcess { } /** - * Checks if the time has been modified. by a task. - * This mehod is needed by the task manager in order to add a clock offset - * to the process object. + * Checks if this process's time has been modified by a task. + * The task manager uses this flag to determine if clock offset + * adjustments are needed after task execution. + * + *

This flag is set when tasks directly modify the process's + * local time, requiring synchronization adjustments.

* - * @return true, if yes + * @return true if the time has been modified since last check + * @see VSTaskManager#runTasks(long) */ public synchronized boolean timeModified() { return timeModified; -- cgit v1.2.3