import { onUnexpectedError } from './errors.js'; import { combinedDisposable, Disposable, DisposableStore, SafeDisposable, toDisposable } from './lifecycle.js'; import { LinkedList } from './linkedList.js'; import { StopWatch } from './stopwatch.js'; // ----------------------------------------------------------------------------------------------------------------------- // Uncomment the next line to print warnings whenever an emitter with listeners is disposed. That is a sign of code smell. // ----------------------------------------------------------------------------------------------------------------------- const _enableDisposeWithListenerWarning = false; // _enableDisposeWithListenerWarning = Boolean("TRUE"); // causes a linter warning so that it cannot be pushed // ----------------------------------------------------------------------------------------------------------------------- // Uncomment the next line to print warnings whenever a snapshotted event is used repeatedly without cleanup. // See https://github.com/microsoft/vscode/issues/142851 // ----------------------------------------------------------------------------------------------------------------------- const _enableSnapshotPotentialLeakWarning = false; export var Event; (function (Event) { Event.None = () => Disposable.None; function _addLeakageTraceLogic(options) { if (_enableSnapshotPotentialLeakWarning) { const { onListenerDidAdd: origListenerDidAdd } = options; const stack = Stacktrace.create(); let count = 0; options.onListenerDidAdd = () => { if (++count === 2) { console.warn('snapshotted emitter LIKELY used public and SHOULD HAVE BEEN created with DisposableStore. snapshotted here'); stack.print(); } origListenerDidAdd === null || origListenerDidAdd === void 0 ? void 0 : origListenerDidAdd(); }; } } /** * Given an event, returns another event which only fires once. */ function once(event) { return (listener, thisArgs = null, disposables) => { // we need this, in case the event fires during the listener call let didFire = false; let result = undefined; result = event(e => { if (didFire) { return; } else if (result) { result.dispose(); } else { didFire = true; } return listener.call(thisArgs, e); }, null, disposables); if (didFire) { result.dispose(); } return result; }; } Event.once = once; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function map(event, map, disposable) { return snapshot((listener, thisArgs = null, disposables) => event(i => listener.call(thisArgs, map(i)), null, disposables), disposable); } Event.map = map; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function forEach(event, each, disposable) { return snapshot((listener, thisArgs = null, disposables) => event(i => { each(i); listener.call(thisArgs, i); }, null, disposables), disposable); } Event.forEach = forEach; function filter(event, filter, disposable) { return snapshot((listener, thisArgs = null, disposables) => event(e => filter(e) && listener.call(thisArgs, e), null, disposables), disposable); } Event.filter = filter; /** * Given an event, returns the same event but typed as `Event`. */ function signal(event) { return event; } Event.signal = signal; function any(...events) { return (listener, thisArgs = null, disposables) => combinedDisposable(...events.map(event => event(e => listener.call(thisArgs, e), null, disposables))); } Event.any = any; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function reduce(event, merge, initial, disposable) { let output = initial; return map(event, e => { output = merge(output, e); return output; }, disposable); } Event.reduce = reduce; function snapshot(event, disposable) { let listener; const options = { onFirstListenerAdd() { listener = event(emitter.fire, emitter); }, onLastListenerRemove() { listener === null || listener === void 0 ? void 0 : listener.dispose(); } }; if (!disposable) { _addLeakageTraceLogic(options); } const emitter = new Emitter(options); disposable === null || disposable === void 0 ? void 0 : disposable.add(emitter); return emitter.event; } function debounce(event, merge, delay = 100, leading = false, leakWarningThreshold, disposable) { let subscription; let output = undefined; let handle = undefined; let numDebouncedCalls = 0; const options = { leakWarningThreshold, onFirstListenerAdd() { subscription = event(cur => { numDebouncedCalls++; output = merge(output, cur); if (leading && !handle) { emitter.fire(output); output = undefined; } clearTimeout(handle); handle = setTimeout(() => { const _output = output; output = undefined; handle = undefined; if (!leading || numDebouncedCalls > 1) { emitter.fire(_output); } numDebouncedCalls = 0; }, delay); }); }, onLastListenerRemove() { subscription.dispose(); } }; if (!disposable) { _addLeakageTraceLogic(options); } const emitter = new Emitter(options); disposable === null || disposable === void 0 ? void 0 : disposable.add(emitter); return emitter.event; } Event.debounce = debounce; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function latch(event, equals = (a, b) => a === b, disposable) { let firstCall = true; let cache; return filter(event, value => { const shouldEmit = firstCall || !equals(value, cache); firstCall = false; cache = value; return shouldEmit; }, disposable); } Event.latch = latch; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function split(event, isT, disposable) { return [ Event.filter(event, isT, disposable), Event.filter(event, e => !isT(e), disposable), ]; } Event.split = split; /** * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the * returned event causes this utility to leak a listener on the original event. */ function buffer(event, flushAfterTimeout = false, _buffer = []) { let buffer = _buffer.slice(); let listener = event(e => { if (buffer) { buffer.push(e); } else { emitter.fire(e); } }); const flush = () => { buffer === null || buffer === void 0 ? void 0 : buffer.forEach(e => emitter.fire(e)); buffer = null; }; const emitter = new Emitter({ onFirstListenerAdd() { if (!listener) { listener = event(e => emitter.fire(e)); } }, onFirstListenerDidAdd() { if (buffer) { if (flushAfterTimeout) { setTimeout(flush); } else { flush(); } } }, onLastListenerRemove() { if (listener) { listener.dispose(); } listener = null; } }); return emitter.event; } Event.buffer = buffer; class ChainableEvent { constructor(event) { this.event = event; this.disposables = new DisposableStore(); } map(fn) { return new ChainableEvent(map(this.event, fn, this.disposables)); } forEach(fn) { return new ChainableEvent(forEach(this.event, fn, this.disposables)); } filter(fn) { return new ChainableEvent(filter(this.event, fn, this.disposables)); } reduce(merge, initial) { return new ChainableEvent(reduce(this.event, merge, initial, this.disposables)); } latch() { return new ChainableEvent(latch(this.event, undefined, this.disposables)); } debounce(merge, delay = 100, leading = false, leakWarningThreshold) { return new ChainableEvent(debounce(this.event, merge, delay, leading, leakWarningThreshold, this.disposables)); } on(listener, thisArgs, disposables) { return this.event(listener, thisArgs, disposables); } once(listener, thisArgs, disposables) { return once(this.event)(listener, thisArgs, disposables); } dispose() { this.disposables.dispose(); } } function chain(event) { return new ChainableEvent(event); } Event.chain = chain; function fromNodeEventEmitter(emitter, eventName, map = id => id) { const fn = (...args) => result.fire(map(...args)); const onFirstListenerAdd = () => emitter.on(eventName, fn); const onLastListenerRemove = () => emitter.removeListener(eventName, fn); const result = new Emitter({ onFirstListenerAdd, onLastListenerRemove }); return result.event; } Event.fromNodeEventEmitter = fromNodeEventEmitter; function fromDOMEventEmitter(emitter, eventName, map = id => id) { const fn = (...args) => result.fire(map(...args)); const onFirstListenerAdd = () => emitter.addEventListener(eventName, fn); const onLastListenerRemove = () => emitter.removeEventListener(eventName, fn); const result = new Emitter({ onFirstListenerAdd, onLastListenerRemove }); return result.event; } Event.fromDOMEventEmitter = fromDOMEventEmitter; function toPromise(event) { return new Promise(resolve => once(event)(resolve)); } Event.toPromise = toPromise; function runAndSubscribe(event, handler) { handler(undefined); return event(e => handler(e)); } Event.runAndSubscribe = runAndSubscribe; function runAndSubscribeWithStore(event, handler) { let store = null; function run(e) { store === null || store === void 0 ? void 0 : store.dispose(); store = new DisposableStore(); handler(e, store); } run(undefined); const disposable = event(e => run(e)); return toDisposable(() => { disposable.dispose(); store === null || store === void 0 ? void 0 : store.dispose(); }); } Event.runAndSubscribeWithStore = runAndSubscribeWithStore; class EmitterObserver { constructor(obs, store) { this.obs = obs; this._counter = 0; this._hasChanged = false; const options = { onFirstListenerAdd: () => { obs.addObserver(this); }, onLastListenerRemove: () => { obs.removeObserver(this); } }; if (!store) { _addLeakageTraceLogic(options); } this.emitter = new Emitter(options); if (store) { store.add(this.emitter); } } beginUpdate(_observable) { // console.assert(_observable === this.obs); this._counter++; } handleChange(_observable, _change) { this._hasChanged = true; } endUpdate(_observable) { if (--this._counter === 0) { if (this._hasChanged) { this._hasChanged = false; this.emitter.fire(this.obs.get()); } } } } function fromObservable(obs, store) { const observer = new EmitterObserver(obs, store); return observer.emitter.event; } Event.fromObservable = fromObservable; })(Event || (Event = {})); class EventProfiling { constructor(name) { this._listenerCount = 0; this._invocationCount = 0; this._elapsedOverall = 0; this._name = `${name}_${EventProfiling._idPool++}`; } start(listenerCount) { this._stopWatch = new StopWatch(true); this._listenerCount = listenerCount; } stop() { if (this._stopWatch) { const elapsed = this._stopWatch.elapsed(); this._elapsedOverall += elapsed; this._invocationCount += 1; console.info(`did FIRE ${this._name}: elapsed_ms: ${elapsed.toFixed(5)}, listener: ${this._listenerCount} (elapsed_overall: ${this._elapsedOverall.toFixed(2)}, invocations: ${this._invocationCount})`); this._stopWatch = undefined; } } } EventProfiling._idPool = 0; let _globalLeakWarningThreshold = -1; class LeakageMonitor { constructor(customThreshold, name = Math.random().toString(18).slice(2, 5)) { this.customThreshold = customThreshold; this.name = name; this._warnCountdown = 0; } dispose() { if (this._stacks) { this._stacks.clear(); } } check(stack, listenerCount) { let threshold = _globalLeakWarningThreshold; if (typeof this.customThreshold === 'number') { threshold = this.customThreshold; } if (threshold <= 0 || listenerCount < threshold) { return undefined; } if (!this._stacks) { this._stacks = new Map(); } const count = (this._stacks.get(stack.value) || 0); this._stacks.set(stack.value, count + 1); this._warnCountdown -= 1; if (this._warnCountdown <= 0) { // only warn on first exceed and then every time the limit // is exceeded by 50% again this._warnCountdown = threshold * 0.5; // find most frequent listener and print warning let topStack; let topCount = 0; for (const [stack, count] of this._stacks) { if (!topStack || topCount < count) { topStack = stack; topCount = count; } } console.warn(`[${this.name}] potential listener LEAK detected, having ${listenerCount} listeners already. MOST frequent listener (${topCount}):`); console.warn(topStack); } return () => { const count = (this._stacks.get(stack.value) || 0); this._stacks.set(stack.value, count - 1); }; } } class Stacktrace { constructor(value) { this.value = value; } static create() { var _a; return new Stacktrace((_a = new Error().stack) !== null && _a !== void 0 ? _a : ''); } print() { console.warn(this.value.split('\n').slice(2).join('\n')); } } class Listener { constructor(callback, callbackThis, stack) { this.callback = callback; this.callbackThis = callbackThis; this.stack = stack; this.subscription = new SafeDisposable(); } invoke(e) { this.callback.call(this.callbackThis, e); } } /** * The Emitter can be used to expose an Event to the public * to fire it from the insides. * Sample: class Document { private readonly _onDidChange = new Emitter<(value:string)=>any>(); public onDidChange = this._onDidChange.event; // getter-style // get onDidChange(): Event<(value:string)=>any> { // return this._onDidChange.event; // } private _doIt() { //... this._onDidChange.fire(value); } } */ export class Emitter { constructor(options) { var _a, _b; this._disposed = false; this._options = options; this._leakageMon = _globalLeakWarningThreshold > 0 ? new LeakageMonitor(this._options && this._options.leakWarningThreshold) : undefined; this._perfMon = ((_a = this._options) === null || _a === void 0 ? void 0 : _a._profName) ? new EventProfiling(this._options._profName) : undefined; this._deliveryQueue = (_b = this._options) === null || _b === void 0 ? void 0 : _b.deliveryQueue; } dispose() { var _a, _b, _c, _d; if (!this._disposed) { this._disposed = true; // It is bad to have listeners at the time of disposing an emitter, it is worst to have listeners keep the emitter // alive via the reference that's embedded in their disposables. Therefore we loop over all remaining listeners and // unset their subscriptions/disposables. Looping and blaming remaining listeners is done on next tick because the // the following programming pattern is very popular: // // const someModel = this._disposables.add(new ModelObject()); // (1) create and register model // this._disposables.add(someModel.onDidChange(() => { ... }); // (2) subscribe and register model-event listener // ...later... // this._disposables.dispose(); disposes (1) then (2): don't warn after (1) but after the "overall dispose" is done if (this._listeners) { if (_enableDisposeWithListenerWarning) { const listeners = Array.from(this._listeners); queueMicrotask(() => { var _a; for (const listener of listeners) { if (listener.subscription.isset()) { listener.subscription.unset(); (_a = listener.stack) === null || _a === void 0 ? void 0 : _a.print(); } } }); } this._listeners.clear(); } (_a = this._deliveryQueue) === null || _a === void 0 ? void 0 : _a.clear(this); (_c = (_b = this._options) === null || _b === void 0 ? void 0 : _b.onLastListenerRemove) === null || _c === void 0 ? void 0 : _c.call(_b); (_d = this._leakageMon) === null || _d === void 0 ? void 0 : _d.dispose(); } } /** * For the public to allow to subscribe * to events from this Emitter */ get event() { if (!this._event) { this._event = (callback, thisArgs, disposables) => { var _a, _b, _c; if (!this._listeners) { this._listeners = new LinkedList(); } const firstListener = this._listeners.isEmpty(); if (firstListener && ((_a = this._options) === null || _a === void 0 ? void 0 : _a.onFirstListenerAdd)) { this._options.onFirstListenerAdd(this); } let removeMonitor; let stack; if (this._leakageMon && this._listeners.size >= 30) { // check and record this emitter for potential leakage stack = Stacktrace.create(); removeMonitor = this._leakageMon.check(stack, this._listeners.size + 1); } if (_enableDisposeWithListenerWarning) { stack = stack !== null && stack !== void 0 ? stack : Stacktrace.create(); } const listener = new Listener(callback, thisArgs, stack); const removeListener = this._listeners.push(listener); if (firstListener && ((_b = this._options) === null || _b === void 0 ? void 0 : _b.onFirstListenerDidAdd)) { this._options.onFirstListenerDidAdd(this); } if ((_c = this._options) === null || _c === void 0 ? void 0 : _c.onListenerDidAdd) { this._options.onListenerDidAdd(this, callback, thisArgs); } const result = listener.subscription.set(() => { removeMonitor === null || removeMonitor === void 0 ? void 0 : removeMonitor(); if (!this._disposed) { removeListener(); if (this._options && this._options.onLastListenerRemove) { const hasListeners = (this._listeners && !this._listeners.isEmpty()); if (!hasListeners) { this._options.onLastListenerRemove(this); } } } }); if (disposables instanceof DisposableStore) { disposables.add(result); } else if (Array.isArray(disposables)) { disposables.push(result); } return result; }; } return this._event; } /** * To be kept private to fire an event to * subscribers */ fire(event) { var _a, _b; if (this._listeners) { // put all [listener,event]-pairs into delivery queue // then emit all event. an inner/nested event might be // the driver of this if (!this._deliveryQueue) { this._deliveryQueue = new PrivateEventDeliveryQueue(); } for (const listener of this._listeners) { this._deliveryQueue.push(this, listener, event); } // start/stop performance insight collection (_a = this._perfMon) === null || _a === void 0 ? void 0 : _a.start(this._deliveryQueue.size); this._deliveryQueue.deliver(); (_b = this._perfMon) === null || _b === void 0 ? void 0 : _b.stop(); } } } export class EventDeliveryQueue { constructor() { this._queue = new LinkedList(); } get size() { return this._queue.size; } push(emitter, listener, event) { this._queue.push(new EventDeliveryQueueElement(emitter, listener, event)); } clear(emitter) { const newQueue = new LinkedList(); for (const element of this._queue) { if (element.emitter !== emitter) { newQueue.push(element); } } this._queue = newQueue; } deliver() { while (this._queue.size > 0) { const element = this._queue.shift(); try { element.listener.invoke(element.event); } catch (e) { onUnexpectedError(e); } } } } /** * An `EventDeliveryQueue` that is guaranteed to be used by a single `Emitter`. */ class PrivateEventDeliveryQueue extends EventDeliveryQueue { clear(emitter) { // Here we can just clear the entire linked list because // all elements are guaranteed to belong to this emitter this._queue.clear(); } } class EventDeliveryQueueElement { constructor(emitter, listener, event) { this.emitter = emitter; this.listener = listener; this.event = event; } } export class PauseableEmitter extends Emitter { constructor(options) { super(options); this._isPaused = 0; this._eventQueue = new LinkedList(); this._mergeFn = options === null || options === void 0 ? void 0 : options.merge; } pause() { this._isPaused++; } resume() { if (this._isPaused !== 0 && --this._isPaused === 0) { if (this._mergeFn) { // use the merge function to create a single composite // event. make a copy in case firing pauses this emitter const events = Array.from(this._eventQueue); this._eventQueue.clear(); super.fire(this._mergeFn(events)); } else { // no merging, fire each event individually and test // that this emitter isn't paused halfway through while (!this._isPaused && this._eventQueue.size !== 0) { super.fire(this._eventQueue.shift()); } } } } fire(event) { if (this._listeners) { if (this._isPaused !== 0) { this._eventQueue.push(event); } else { super.fire(event); } } } } export class DebounceEmitter extends PauseableEmitter { constructor(options) { var _a; super(options); this._delay = (_a = options.delay) !== null && _a !== void 0 ? _a : 100; } fire(event) { if (!this._handle) { this.pause(); this._handle = setTimeout(() => { this._handle = undefined; this.resume(); }, this._delay); } super.fire(event); } } /** * The EventBufferer is useful in situations in which you want * to delay firing your events during some code. * You can wrap that code and be sure that the event will not * be fired during that wrap. * * ``` * const emitter: Emitter; * const delayer = new EventDelayer(); * const delayedEvent = delayer.wrapEvent(emitter.event); * * delayedEvent(console.log); * * delayer.bufferEvents(() => { * emitter.fire(); // event will not be fired yet * }); * * // event will only be fired at this point * ``` */ export class EventBufferer { constructor() { this.buffers = []; } wrapEvent(event) { return (listener, thisArgs, disposables) => { return event(i => { const buffer = this.buffers[this.buffers.length - 1]; if (buffer) { buffer.push(() => listener.call(thisArgs, i)); } else { listener.call(thisArgs, i); } }, undefined, disposables); }; } bufferEvents(fn) { const buffer = []; this.buffers.push(buffer); const r = fn(); this.buffers.pop(); buffer.forEach(flush => flush()); return r; } } /** * A Relay is an event forwarder which functions as a replugabble event pipe. * Once created, you can connect an input event to it and it will simply forward * events from that input event through its own `event` property. The `input` * can be changed at any point in time. */ export class Relay { constructor() { this.listening = false; this.inputEvent = Event.None; this.inputEventListener = Disposable.None; this.emitter = new Emitter({ onFirstListenerDidAdd: () => { this.listening = true; this.inputEventListener = this.inputEvent(this.emitter.fire, this.emitter); }, onLastListenerRemove: () => { this.listening = false; this.inputEventListener.dispose(); } }); this.event = this.emitter.event; } set input(event) { this.inputEvent = event; if (this.listening) { this.inputEventListener.dispose(); this.inputEventListener = event(this.emitter.fire, this.emitter); } } dispose() { this.inputEventListener.dispose(); this.emitter.dispose(); } }