Merge branch 'XX-4425/DummyMessagePauseAndResume' into 'release'

WIP: Add Resume/Pause bindings to Dummy

See merge request !55

wasm/dummy.go

@@ -26,7 +26,8 @@ type DummyTraffic struct {
 func newDummyTrafficJS(newDT *bindings.DummyTraffic) map[string]any {
 	dt := DummyTraffic{newDT}
 	dtMap := map[string]any{
-		"SetStatus": js.FuncOf(dt.SetStatus),
+		"Pause":     js.FuncOf(dt.Pause),
+		"Start":     js.FuncOf(dt.Start),
 		"GetStatus": js.FuncOf(dt.GetStatus),
 	}
 
@@ -34,11 +35,11 @@ func newDummyTrafficJS(newDT *bindings.DummyTraffic) map[string]any {
 }
 
 // NewDummyTrafficManager creates a [DummyTraffic] manager and initialises the
-// dummy traffic sending thread. Note that the manager does not start sending
-// dummy traffic until true is passed into [DummyTraffic.SetStatus]. The time
-// duration between each sending operation and the amount of messages sent each
-// interval are randomly generated values with bounds defined by the given
-// parameters below.
+// dummy traffic sending thread. Note that the manager is by default paused,
+// and as such the sending thread must be started by calling [DummyTraffic.Start].
+// The time duration between each sending operation and the amount of messages
+// sent each interval are randomly generated values with bounds defined by the
+// given parameters below.
 //
 // Parameters:
 //   - args[0] - A [Cmix] object ID in the tracker (int).
@@ -64,22 +65,34 @@ func NewDummyTrafficManager(_ js.Value, args []js.Value) any {
 	return newDummyTrafficJS(dt)
 }
 
-// SetStatus sets the state of the [DummyTraffic] manager's send thread by
-// passing in a boolean parameter. There may be a small delay in between this
-// call and the status of the sending thread to change accordingly. For example,
-// passing false into this call while the sending thread is currently sending
-// messages will not cancel nor halt the sending operation, but will pause the
-// thread once that operation has completed.
+// Pause will pause the [DummyTraffic]'s sending thread, meaning messages will no
+// longer be sent. After calling Pause, the sending thread may only be resumed
+// by calling Resume.
 //
-// Parameters:
-//   - args[0] - Input should be true if you want to send dummy messages and
-//     false if you want to pause dummy messages (boolean).
+// There may be a small delay between this call and the pause taking effect.
+// This is because Pause will not cancel the thread when it is in the process
+// of sending messages, but will instead wait for that thread to complete. The
+// thread will then be prevented from beginning another round of sending.
+func (dt *DummyTraffic) Pause(js.Value, []js.Value) any {
+	err := dt.api.Pause()
+	if err != nil {
+		utils.Throw(utils.TypeError, err)
+		return nil
+	}
+
+	return nil
+}
+
+// Start will start up the [DummyTraffic]'s sending thread, meaning messages will
+//  be sent. This should be called after calling NewManager, as by default the
+//  thread is paused. This may also be called after a call to [DummyTraffic.Pause].
 //
-// Returns:
-//   - Throws a TypeError if the [DummyTraffic.SetStatus] is called too
-//     frequently, causing the internal status channel to fill.
-func (dt *DummyTraffic) SetStatus(_ js.Value, args []js.Value) any {
-	err := dt.api.SetStatus(args[0].Bool())
+// This will re-initialize the sending thread with a new randomly generated
+// interval between sending dummy messages. This means that there is zero
+// guarantee that the sending interval prior to pausing will be the same
+// sending interval after a call to Start.
+func (dt *DummyTraffic) Start(js.Value, []js.Value) any {
+	err := dt.api.Start()
 	if err != nil {
 		utils.Throw(utils.TypeError, err)
 		return nil
@@ -89,16 +102,14 @@ func (dt *DummyTraffic) SetStatus(_ js.Value, args []js.Value) any {
 }
 
 // GetStatus returns the current state of the [DummyTraffic] manager's sending
-// thread. Note that this function does not return the status set by the most
-// recent call to [DummyTraffic.SetStatus]. Instead, this call returns the
-// current status of the sending thread. This is due to the small delay that may
-// occur between calling [DummyTraffic.SetStatus] and the sending thread taking
-// into effect that status change.
+// thread. Note that the status returned here may lag behind a user's earlier
+// call to pause the sending thread. This is a result of a small delay (see
+// [DummyTraffic.Pause] for more details)
 //
 // Returns:
-//   - Returns true if sending thread is sending dummy messages and false if
-//     sending thread is paused/stopped and is not sending dummy messages
-//     (boolean).
+//   - bool - Returns true ([dummy.Running]) if the sending thread is sending
+//     messages and false ([dummy.Paused]) if the sending thread is not sending
+//     messages.
 func (dt *DummyTraffic) GetStatus(js.Value, []js.Value) any {
 	return dt.api.GetStatus()
 }