User interface events often arrive in bursts. A search box changes on every keystroke, a window fires a stream of resize events, and a data feed can update many times a second. Running an expensive refresh for each event wastes work, because only the state at the end of the burst matters.

TThrottledEvent in Sphere 10 Pascal Framework is a component that sits between the event source and the handler and decides when the handler actually runs. This article covers its delivery modes, how to wire it up, how to observe and cancel pending delivery, and the lifetime rules for its listeners.

1. Let TThrottledEvent own the delivery policy

Setting up the component takes four statements. The sample creates it without an owner, sets a 100 millisecond interval, selects the trailing mode, which delivers once after a burst has gone quiet, and registers one listener.

constructor TInputHandler.Create;
begin
  inherited Create;
  FRefresh := TThrottledEvent.Create(nil);
  FRefresh.Interval := TTimeSpan.FromMilliseconds(100);
  FRefresh.Mode := temNotifyOnEventBurstFinished;
  FRefresh.Add(HandleLatest);
end;

Interval is a TTimeSpan and defaults to one second. Add accepts any TNotifyEvent, and several listeners can be registered. Its optional second parameter, ExecuteMainThread, dispatches that listener through the main thread.

The input handler stores whatever state the listener will need and then calls Notify.

procedure TInputHandler.SetInput(const AValue: String);
begin
  FInput := AValue;
  FRefresh.Notify;
end;

The listener is an ordinary method that reads the latest state when it finally runs. Notify passes no arguments, so the listener always sees the current value rather than the value at the time of any particular notification.

procedure TInputHandler.HandleLatest(Sender: TObject);
begin
  Inc(FDeliveries);
  FHandled := FInput;
end;

Three calls to SetInput within the interval produce one call to HandleLatest, which sees the third value.

3 notifications, deliveries=1, handled=abc

Writing this by hand takes a TTimer that is restarted on every input, a Boolean that tracks whether a delivery is pending, and matching code to clear both on cancellation.

2. How TThrottledEvent delivers

---
config:
  sequence:
    actorMargin: 8
    width: 96
    mirrorActors: false
    messageMargin: 28
    noteMargin: 8
---
sequenceDiagram
    participant S as Event source
    participant T as TThrottledEvent
    participant L as Listener
    S->>T: Notify
    S->>T: Notify
    S->>T: Notify
    Note over T: timer restarts each time
    Note over T: quiet for Interval
    T->>L: called once

3. Observe and cancel pending delivery

In the two burst modes the component exposes the state of the current burst.

procedure TInputHandler.Cancel;
begin
  FRefresh.Cancel;
end;

function TInputHandler.Waiting: Boolean;
begin
  Result := FRefresh.Waiting;
end;

stateDiagram-v2
    direction TB
    [*] --> Idle
    Idle --> Waiting: first Notify
    Waiting --> Waiting: Notify or Postpone
    Waiting --> Idle: quiet, listener runs
    Waiting --> Idle: Cancel

4. Keep pending input separate from running work

Waiting describes the input burst only. If a listener starts asynchronous work, that work needs its own busy state and its own cancellation.

The component is driven by a VCL or LCL TTimer, so it needs a running message loop and delivers on the thread that owns that loop. The interval is a minimum quiet time and not an exact deadline, because the operating system schedules timer messages.

The component does not keep its listeners' targets alive. Free the component, or call Remove, before destroying an object whose method is registered. Giving the component a form as its owner ties its lifetime to that form.

5. Choose a different delivery mode

Switching policy is a one-line change to Mode, and the notifying code and the listeners stay the same. The Framework's interactive timing example lets you try each mode and watch separate counters for notifications and deliveries.

6. Get the Framework and run the example

Get Sphere 10 Pascal Framework and follow its package instructions . The sample uses the UCommon and UCommon.UI units together with the VCL or LCL timer and forms units.

The sample sends three notifications inside one interval, waits for the single delivery, then schedules another and cancels it. It was built and run with Free Pascal 3.2.0 on Windows using the Lazarus Win32 widgetset, against Pascal Framework revision 2cc6558a91714086d02a358714bda01e0c06849d. Its Build.ps1 accepts the Framework, FPC, Lazarus and output paths.

Download the complete runnable sample.

For the broader Sphere 10 development toolkit, see the Sphere10 Framework overview .

Author: Herman Schoenfeld