virtualtimescheduler.md

Rx.VirtualTimeScheduler class

Base class for providing scheduling in virtual time. This inherits from the Rx.Scheduler class.

Usage

The following shows an example of using the Rx.VirtualTimeScheduler. In order for this to work, you must implement the add, toAbsoluteTime and toRelativeTime methods as described below.

/* Comparer required for scheduling priority */
function comparer (x, y) {
  if (x > y) { return 1; }
  if (x < y) { return -1; }
  return 0;
}

var scheduler = new Rx.VirtualTimeScheduler(0, comparer);

/**
 * Adds a relative time value to an absolute time value.
 * @param {Any} absolute Absolute virtual time value.
 * @param {Any} relative Relative virtual time value to add.
 * @return {Any} Resulting absolute virtual time sum value.
 */
scheduler.add = function (absolute, relative) {
  return absolute + relative;
};

/**
 * Converts an absolute time to a number
 * @param {Number} The absolute time in ms
 * @returns {Number} The absolute time in ms
 */
scheduler.toAbsoluteTime = function (absolute) {
  return new Date(absolute);
};

/**
 * Converts the time span number/Date to a relative virtual time value.
 * @param {Number} timeSpan TimeSpan value to convert.
 * @return {Number} Corresponding relative virtual time value.
 */
scheduler.toRelativeTime = function (timeSpan) {
  return timeSpan;
};

// Schedule some time
scheduler.scheduleAbsolute(null, new Date(1), function () { console.log('foo'); });
scheduler.scheduleAbsolute(null, new Date(2), function () { console.log('bar'); });
scheduler.scheduleAbsolute(null, new Date(3), function () { scheduler.stop(); });

// Start the scheduler
scheduler.start();

// => foo
// => bar

// Check the clock once stopped
console.log(scheduler.now());
// => 3

console.log(scheduler.clock);
// => 3

Location

File:

• virtualtimescheduler.js

Dist:

• rx.all.js
• rx.all.compat.js
• rx.virtualtime.js

VirtualTimeScheduler Constructor

• constructor

VirtualTimeScheduler Instance Methods

• advanceBy
• advanceTo
• scheduleAbsolute
• scheduleRelative
• sleep
• start
• stop

VirtualTimeScheduler Instance Properties

• isEnabled

VirtualTimeScheduler Protected Abstract Methods

• add
• toAbsoluteTime
• toRelativeTime

VirtualTimeScheduler Protected Methods

• getNext

Inherited Classes

• Rx.Scheduler

VirtualTimeScheduler Constructor

Rx.VirtualTimeScheduler(initialClock, comparer)

# Ⓢ

Creates a new virtual time scheduler with the specified initial clock value and absolute time comparer.

Arguments

1. initialClock (Function): Initial value for the clock.
2. comparer (Function): Comparer to determine causality of events based on absolute time.

Example

function comparer (x, y) {
  if (x > y) { return 1; }
  if (x < y) { return -1; }
  return 0;
}

var scheduler = new Rx.VirtualTimeScheduler(
  0,          /* initial clock of 0 */
  comparer    /* comparer for determining order */
);

---

VirtualTimeScheduler Instance Methods

Rx.VirtualTimeScheduler.prototype.advanceBy(time)

# Ⓢ

Advances the scheduler's clock by the specified relative time, running all work scheduled for that timespan.

Arguments

1. time (Any): Relative time to advance the scheduler's clock by.

Example

var scheduler = new MyVirtualScheduler(
  200 /* initial time */
);

scheduler.scheduleAbsolute(null, 250, function () {
  console.log('hello');
});

scheduler.advanceBy(300);
// => hello

console.log(scheduler.clock);
// => 500

---

Rx.VirtualTimeScheduler.prototype.advanceTo(time)

# Ⓢ

Advances the scheduler's clock to the specified time, running all work till that point.

Arguments

1. time (Any): Absolute time to advance the scheduler's clock to.

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.scheduleAbsolute(null, 100, function () {
  console.log('hello');
});

scheduler.scheduleAbsolute(null, 200, function () {
  console.log('world');
});

scheduler.advanceBy(300);
// => hello
// => world

console.log(scheduler.clock);
// => 300

---

Rx.VirtualTimeScheduler.prototype.scheduleAbsolute(state, dueTime, action)

# Ⓢ

Schedules an action to be executed at dueTime.

Arguments

1. state: (Any): State passed to the action to be executed.
2. dueTime (Any): Absolute time at which to execute the action.
3. action: Function: Action to execute with the following arguments:
4. scheduler: Scheduler - The current Scheduler
5. state: Any - The current state

Returns

(Disposable): The disposable object used to cancel the scheduled action (best effort).

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.scheduleAbsolute('world', 100, function (scheduler, state) {
  console.log('hello ' + state);
});

scheduler.scheduleAbsolute('moon', 200, function (scheduler, state) {
  console.log('goodnight ' + state);
});

scheduler.start();
// => hello world
// => goodnight moon

console.log(scheduler.clock);
// => 200

---

Rx.VirtualTimeScheduler.prototype.scheduleRelative(state, dueTime, action)

# Ⓢ

Schedules an action to be executed at dueTime.

Arguments

1. state: (Any): State passed to the action to be executed.
2. dueTime (Any): Relative time after which to execute the action.
3. action: Function: Action to execute with the following arguments:
4. scheduler: Scheduler - The current Scheduler
5. state: Any - The current state

Returns

(Disposable): The disposable object used to cancel the scheduled action (best effort).

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.scheduleRelative('world', 100, function (scheduler, state) {
  console.log('hello ' + state);
});

scheduler.scheduleRelative('moon', 200, function (scheduler, state) {
  console.log('goodnight ' + state);
});

scheduler.start();
// => hello world
// => goodnight moon

console.log(scheduler.clock);
// => 300

---

Rx.VirtualTimeScheduler.prototype.sleep(time)

# Ⓢ

Advances the scheduler's clock by the specified relative time.

Arguments

1. time (Any): Relative time to advance the scheduler's clock by.

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.sleep(400);

console.log(scheduler.clock);
// => 400

---

Rx.VirtualTimeScheduler.prototype.start()

# Ⓢ

Starts the virtual time scheduler.

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.scheduleRelative('world', 100, function (scheduler, state) {
  console.log('hello ' + state);
});

scheduler.scheduleRelative('moon', 200, function (scheduler, state) {
  console.log('goodnight ' + state);
});

scheduler.start();
// => hello world
// => goodnight moon

console.log(scheduler.clock);
// => 400

---

Rx.VirtualTimeScheduler.prototype.stop()

# Ⓢ

Stops the virtual time scheduler.

Example

var scheduler = new MyVirtualScheduler(
  0 /* initial time */
);

scheduler.scheduleRelative('world', 100, function (scheduler, state) {
  console.log('hello ' + state);
});

scheduler.scheduleRelative(null, 100, function (scheduler, state) {
  scheduler.stop();
});

scheduler.scheduleRelative(null, 100, function (scheduler, state) {
  console.log('goodbye cruel ' + state);
});

scheduler.start();
// => hello world

---

VirtualTimeScheduler Abstract Protected Methods

Rx.VirtualTimeScheduler.prototype.add(absolute, relative)

# Ⓢ

Adds a relative time value to an absolute time value. This method is used in several methods including scheduleRelative, advanceBy and sleep.

Arguments

1. absolute (Any): Absolute virtual time value.
2. relative (Any): Relative virtual time value.

Returns

(Any): Resulting absolute virtual time sum value.

Example

One possible implementation could be as simple as the following:

scheduler.add = function (absolute, relative) {
    return absolute + relative;
};

---

Rx.VirtualTimeScheduler.prototype.toAbsoluteTime(absolute)

# Ⓢ

Converts an absolute time to a number. This is used directly in the now method on the Rx.Scheduler

Arguments

1. absolute (Any): The absolute time to convert.

Returns

(Number): The absolute time in ms.

Example

One possible implementation could be as simple as the following:

// String -> Number
scheduler.toAbsoluteTime = function (absolute) {
  return absolute.length;
};

---

Rx.VirtualTimeScheduler.prototype.toRelativeTime(timeSpan)

# Ⓢ

Converts the time span number/Date to a relative virtual time value.

Arguments

1. timeSpan (Any): The time span number value to convert. This is used directly in scheduleFuture.

Returns

(Number): Corresponding relative virtual time value.

Example

One possible implementation could be as simple as the following:

// Number -> Number
scheduler.toRelativeTime = function (timeSpan) {
  return timeSpan;
};

---