`throttle`

wait 구간마다 함수를 최대 한 번만 실행합니다 — debounce의 "잠잠해질 때까지 기다리기"와 달리 일정한 주기로 발화합니다.

Throttled<T> throttle<T>(void Function(T arg) func, Duration wait, {bool leading = true, bool trailing = true}) class Throttled<T> { void call(T arg); // Throttled is callable: throttled(arg) void cancel(); } FxEvents<T> FxEvents<T>.throttle(Duration window, {bool leading = true, bool trailing = false}) // chain (events) Throttled<T> (void Function(T arg)).fxThrottle(Duration wait, {bool leading = true, bool trailing = true}) // method

강의

throttle은 감싼 함수가 아무리 자주 호출되더라도 func가 wait마다 최대 한 번만 실행되도록 보장합니다. debounce와의 결정적인 차이가 여기 있습니다. debounce는 호출이 있을 때마다 타이머를 다시 시작하므로 호출이 끊이지 않으면 실행이 무한정 밀릴 수 있지만, throttle의 구간은 한 번 시작되면 고정이라 호출이 일정한 주기로 계속 통과합니다. 스크롤이나 리사이즈 핸들러처럼 맨 마지막 한 번이 아니라 주기적인 갱신이 필요한 곳에 유용합니다.

leading과 trailing은 둘 다 기본값이 true입니다. 한 구간의 첫 호출은 즉시 발화하고(리딩 에지), 구간이 닫히기 전에 호출이 더 들어오면 그중 마지막 호출이 구간이 끝날 때 한 번 발화합니다(트레일링 에지, 가장 최근 인자로). 둘 중 하나를 끄면 리딩만 또는 트레일링만 동작하게 만들 수 있습니다. debounce와 마찬가지로 반환되는 Throttled<T>는 호출 가능한 클래스이며, 대기 중인 트레일링 호출을 버리는 .cancel()을 제공합니다.

데모 1 · 리딩 + 트레일링(기본 동작)

첫 호출은 즉시 발화하고, 구간이 닫힐 때 그 구간의 마지막 호출이 한 번 더 발화합니다:

데모 2 · leading/trailing 조절과 cancel()

leading을 끄면 트레일링만, trailing을 끄면 리딩만 동작하고, .cancel()을 호출하면 대기 중인 트레일링 호출을 버립니다.

import 'package:fxdart/fxdart.dart';

Future<void> main() async {
  // leading: false — suppress the immediate call, only the trailing edge fires.
  final trailingOnlyCalls = <String>[];
  final trailingOnly = throttle<String>(
      (s) => trailingOnlyCalls.add(s), const Duration(milliseconds: 100),
      leading: false, trailing: true);
  trailingOnly('a');
  trailingOnly('b');
  print(trailingOnlyCalls); // [] — no leading call this time
  await sleep(const Duration(milliseconds: 150));
  print(trailingOnlyCalls); // [b]

// trailing: false — only the leading edge ever fires.
  final leadingOnlyCalls = <String>[];
  final leadingOnly = throttle<String>(
      (s) => leadingOnlyCalls.add(s), const Duration(milliseconds: 100),
      leading: true, trailing: false);
  leadingOnly('x');
  leadingOnly('y');
  leadingOnly('z');
  await sleep(const Duration(milliseconds: 150));
  print(leadingOnlyCalls); // [x] — y and z are dropped, no trailing call

// .cancel() drops a pending trailing call.
  final cancelCalls = <String>[];
  final cancelThrottled = throttle<String>(
      (s) => cancelCalls.add(s), const Duration(milliseconds: 100));
  cancelThrottled('first');
  cancelThrottled('second'); // would trigger a trailing call...
  cancelThrottled.cancel(); // ...but this cancels it
  await sleep(const Duration(milliseconds: 150));
  print(cancelCalls); // [first]
}

메서드 표기

debounce와 같습니다. onScroll.fxThrottle(wait)는 throttle(onScroll, wait)이고, leading과 trailing도 그대로 전달합니다.

void onScroll(double offset) => _measure(offset);

final handler = onScroll.fxThrottle(
  const Duration(milliseconds: 100),
  trailing: false,
);

fx 접두사는 감싸는 주체가 어느 라이브러리인지 밝혀 줍니다 — fx의 getter 표기와 같은 규칙입니다.

직접 해 보기

연습: onClick을 throttle로 감싸(wait는 100ms) 빠르게 이어진 클릭이 세 번이 아니라 최대 두 번 — 리딩과 트레일링 — 만 기록되게 만들어 보세요.

이벤트 스트림에서

같은 아이디어가 이벤트 레이어에도 있습니다. 수다스러운 대상이 콜백이 아니라 Stream이라면 fxEvents(s).throttle(window, trailing: …)이 윈도마다 이벤트 하나만 통과시킵니다. 기본값이 하나 다릅니다: 스트림 형태는 trailing: true를 넘기지 않는 한 리딩 전용입니다(위의 콜백 래퍼는 양쪽 에지가 기본으로 켜져 있습니다). 이 체인이 속한 곳은 fxEvents 문서를 참고하세요.

import 'dart:async';

import 'package:fxdart/fxdart.dart';

/// Emits each (offsetMs, value) pair at its offset, closing at [closeMs].
Stream<T> timed<T>(List<(int, T)> events, int closeMs) {
  final c = StreamController<T>();
  for (final (ms, v) in events) {
    Timer(Duration(milliseconds: ms), () => c.add(v));
  }
  Timer(Duration(milliseconds: closeMs), c.close);
  return c.stream;
}

Future<void> main() async {
  // The same idea on a Stream: scroll positions fire constantly; one
  // per 100ms window gets through. Default is leading only.
  final leading = await fxEvents(timed(
          [(0, 0), (30, 40), (60, 90), (130, 160), (160, 220), (300, 400)],
          450))
      .throttle(const Duration(milliseconds: 100))
      .toList();
  print(leading); // [0, 160, 400] — the first event of each window

// trailing: true emits the NEWEST value seen when each window ends —
  // note the stream form defaults to trailing: false, unlike the
  // callback wrapper above.
  final trailing = await fxEvents(
          timed([(0, 0), (30, 40), (60, 90), (130, 160), (300, 400)], 450))
      .throttle(const Duration(milliseconds: 100),
          leading: false, trailing: true)
      .toList();
  print(trailing); // [90, 160, 400]
}

관련 항목: debounce — 고정된 주기가 아니라 잠잠해지기를 기다립니다 · delay & sleep — 타이밍 데모를 만드는 재료 · shuffle — 시드를 지정하는 난수 · concurrent — 비동기 파이프라인의 속도 제한