fix(timing): matching and timing were overwhelming main loop

Author: asmodeus812

README.md

@@ -92,13 +92,6 @@ with ease, as the picker will only ever render and decorate a small subset of th
     - [Using lazy.nvim](#using-lazynvim)
     - [Using vim-plug](#using-vim-plug)
 - [Configuration](#configuration)
-- [Tracing](#tracing)
-- [Workers](#workers)
-- [Pool](#pool)
-    - [Lifecycle](#lifecycle)
-    - [Normalization](#normalization)
-    - [Pruning](#pruning)
-    - [Misc](#misc)
 - [Quickstart](#quickstart)
     - [User command](#user-command)
     - [Static table](#static-table)
@@ -137,7 +130,17 @@ with ease, as the picker will only ever render and decorate a small subset of th
     - [Context aware](#context-aware)
     - [Static tables](#static-tables)
     - [Basic ui.select](#basic-uiselect)
-    - [Advanced ui.select](#advanced-uiselect)
+- [Advanced ui.select](#advanced-uiselect)
+- [Tracing](#tracing)
+- [Scheduler](#scheduler)
+- [Registry](#registry)
+- [Async](#async)
+- [Workers](#workers)
+- [Pool](#pool)
+    - [Lifecycle](#lifecycle)
+    - [Normalization](#normalization)
+    - [Pruning](#pruning)
+    - [Others](#others)
 - [Requirements](#requirements)
     - [Mandatory](#mandatory)
     - [Optional](#optional)
@@ -234,97 +237,6 @@ Configuration details:
 - `registry.prune_interval`: Interval in milliseconds for registry cleanup.
 - `registry.trace`: Optional debug hook `function(event, data)` for registry lifecycle tracing.
 
-## Tracing
-
-Several singleton modules expose a `trace` hook for lightweight diagnostics. Each hook receives `function(event, data)` where `event` is a
-string and `data` is a small table of relevant fields.
-
-Supported modules:
-
-- `pool.trace`: Allocation/reuse, normalization, return, and prune events.
-- `scheduler.trace`: Scheduler start, idle, and setup events.
-- `async.trace`: Async creation and completion events.
-- `registry.trace`: Registry registration, touch, removal, and prune events.
-
-## Workers
-
-Workers are internal coordination helpers that sit on top of the async scheduler. They are not user-configurable, but they define how
-different subsystems sequence work so ordering is deterministic even under heavy async load.
-
-There are two worker modes used in the codebase:
-
-- **Coalescer**: Keeps only the latest request while work is in flight. This is used for UI rendering in `Select`, where multiple list updates
-  can arrive rapidly. The coalescer guarantees that only the most recent render request runs, so stale intermediate renders are dropped.
-
-- **Queue**: Runs every request in strict FIFO order. This is used for stream processing, where chunk order is semantically important. The
-  queue executes tasks one after the other, and each task can yield without allowing another queued task to start early.
-
-Workers are cooperative: each task runs inside an `Async` coroutine and may call `Async.yield()`. Yielding allows other unrelated async tasks
-to run, but does not violate the ordering guarantees within a worker.
-
-## Pool
-
-The pool is a table-reuse subsystem that keeps allocation pressure low for hot paths (streaming, matching, selection). It is a single global
-pool created during `setup()` and reused by the rest of the runtime. The pool is not a cache of results and does not preserve semantic data;
-it only manages table instances and their sizes.
-
-This implementation is **bucketed and deterministic**: tables are normalized into size buckets on return, and future `obtain()` calls return
-the smallest idle table that fits the requested size. There is no adaptive priming or background allocation. Normalization keeps the pool
-stable and prevents it from filling with many distinct odd sizes.
-
-### Lifecycle
-
-**Obtain**
-
-`Pool.obtain(size)` returns a reusable table for scratch work.
-
-- If `size` is provided and greater than 0, the pool returns the **smallest idle table whose size is >= size**.
-- If no idle table is large enough, the pool falls back to the largest available idle table.
-- If the pool is empty, it allocates a fresh table sized to the normalized bucket for the requested size.
-- The returned table is tracked as “in use” and not eligible for pruning.
-
-**Return**
-
-`Pool._return(tbl)` releases a table back to the pool:
-
-- The table is normalized to a bucket size (power-of-two) within `[prime_min, prime_max]`.
-- If `max_tables == 0`, the table is discarded immediately (no pooling).
-- Otherwise, the table is inserted into the idle pool and becomes eligible for reuse.
-
-For code paths that create tables outside of `obtain()` but still need tracking, `Pool.attach(tbl)` and `Pool.detach(tbl)` mark tables as
-in-use without putting them into the idle pool.
-
-### Normalization
-
-Normalization keeps reuse stable across runs:
-
-- Sizes below `prime_min` are kept as-is.
-- Sizes in `[prime_min, prime_max]` are rounded up to the next power-of-two bucket.
-- Sizes above `prime_max` are clamped down to `prime_max` before pooling.
-
-This means a `125000`-element table becomes `131072`, and a `600000`-element table becomes `524288` (default `prime_max`). The pool prefers
-these normalized buckets to avoid fragmentation.
-
-### Pruning
-
-The pool runs a background prune timer:
-
-- Tables idle longer than `max_idle` are discarded.
-- If `max_tables` is set, the pool removes the least-recently-used idle tables until the limit is satisfied.
-- Tables marked “in use” are never pruned.
-
-### Misc
-
-Beyond `obtain()`/`_return()`, the pool exposes a few utility helpers:
-
-- `Pool.attach(tbl)`: mark a table as “in use” without placing it into the idle pool. Use this when you create a table outside
-  `obtain()` but still want the pool to track it.
-- `Pool.detach(tbl)`: remove a table from pool tracking without returning it to the idle pool.
-- `Pool.is_pooled(tbl)`: returns `true` if the table is tracked by the pool (in use or idle).
-- `Pool.fill(tbl, value)`: in-place fill of a table with a single value.
-- `Pool.resize(tbl, size, default)`: resize a table to `size`, filling new slots with `default` when expanding.
-- `Pool.remove(tbl, value)`: remove all entries that match `value` from `tbl`.
-
 ## Quickstart
 
 The examples below create unique instance of a Picker, it is important for users to take note of the fact `it is recommended that you
@@ -1873,6 +1785,131 @@ vim.ui.select = function(items, opts, on_choice)
 )
 ```
 
+## Tracing
+
+Several singleton modules expose a `trace` hook for lightweight diagnostics. Each hook receives `function(event, data)` where `event` is a
+string and `data` is a small table of relevant fields.
+
+Supported modules:
+
+- `pool.trace`: Allocation/reuse, normalization, return, and prune events.
+- `scheduler.trace`: Scheduler start, idle, and setup events.
+- `worker.trace`: Worker cooperative job management
+- `async.trace`: Async creation and completion events.
+- `registry.trace`: Registry registration, touch, removal, and prune events.
+
+## Scheduler
+
+The scheduler is a **singleton cooperative runtime** that drives `Async` coroutines. It owns a single libuv check handle and an in-memory
+queue of runnable async jobs. Any module that needs background work schedules an `Async` instance through `Scheduler.add()`.
+
+Key properties:
+
+- **Budgeted execution**: The scheduler runs a batch of async steps up to a time budget (`async_budget`, in microseconds).
+- **Cooperative**: Each async job yields explicitly; the scheduler never preempts.
+- **Singleton**: There is only one scheduler, initialized during `setup()`.
+
+## Registry
+
+The registry is a **singleton picker manager** that tracks active pickers and prunes stale hidden ones. It is used to prevent long-lived
+pickers from piling up after they are closed or hidden.
+
+Key properties:
+
+- **Idle tracking**: Each picker receives a `last_used` timestamp.
+- **Pruning**: A periodic timer checks for idle pickers and closes them if they are not in use.
+- **Safety checks**: A picker is never pruned while it is open, running a stream, or running a match.
+
+## Async
+
+`Async` is the low-level coroutine wrapper that powers all cooperative work in the plugin. It is not tied to any picker or UI state; it is
+used by the scheduler, worker helpers, streaming, and matching.
+
+Key properties:
+
+- **Explicit yielding**: Work continues only when `Async.yield()` is called.
+- **Cancelable**: Async jobs can be canceled, which is used to prevent stale work from completing.
+- **Traceable**: `async.trace` hooks allow diagnosing lifecycle events for unit tests and performance analysis.
+
+## Workers
+
+Workers are internal coordination helpers that sit on top of the async scheduler. They are not user-configurable, but they define how
+different subsystems sequence work so ordering is deterministic even under heavy async load.
+
+There are two worker modes used in the codebase:
+
+- **Coalesce**: Keeps only the latest request while work is in flight. This is used for UI rendering in `Select`, where multiple list updates
+  can arrive rapidly. The coalesce guarantees that only the most recent render request runs, so stale intermediate renders are dropped.
+
+- **Queue**: Runs every request in strict FIFO order. This is used for stream processing, where chunk order is semantically important. The
+  queue executes tasks one after the other, and each task can yield without allowing another queued task to start early.
+
+Workers are cooperative: each task runs inside an `Async` coroutine and may call `Async.yield()`. Yielding allows other unrelated async tasks
+to run, but does not violate the ordering guarantees within a worker.
+
+## Pool
+
+The pool is a table-reuse subsystem that keeps allocation pressure low for hot paths (streaming, matching, selection). It is a single global
+pool created during `setup()` and reused by the rest of the runtime. The pool is not a cache of results and does not preserve semantic data;
+it only manages table instances and their sizes.
+
+This implementation is **bucketed and deterministic**: tables are normalized into size buckets on return, and future `obtain()` calls return
+the smallest idle table that fits the requested size. There is no adaptive priming or background allocation. Normalization keeps the pool
+stable and prevents it from filling with many distinct odd sizes.
+
+### Lifecycle
+
+**Obtain**
+
+`Pool.obtain(size)` returns a reusable table for scratch work.
+
+- If `size` is provided and greater than 0, the pool returns the **smallest idle table whose size is >= size**.
+- If no idle table is large enough, the pool falls back to the largest available idle table.
+- If the pool is empty, it allocates a fresh table sized to the normalized bucket for the requested size.
+- The returned table is tracked as “in use” and not eligible for pruning.
+
+**Return**
+
+`Pool._return(tbl)` releases a table back to the pool:
+
+- The table is normalized to a bucket size (power-of-two) within `[prime_min, prime_max]`.
+- If `max_tables == 0`, the table is discarded immediately (no pooling).
+- Otherwise, the table is inserted into the idle pool and becomes eligible for reuse.
+
+For code paths that create tables outside of `obtain()` but still need tracking, `Pool.attach(tbl)` and `Pool.detach(tbl)` mark tables as
+in-use without putting them into the idle pool.
+
+### Normalization
+
+Normalization keeps reuse stable across runs:
+
+- Sizes below `prime_min` are kept as-is.
+- Sizes in `[prime_min, prime_max]` are rounded up to the next power-of-two bucket.
+- Sizes above `prime_max` are clamped down to `prime_max` before pooling.
+
+This means a `125000`-element table becomes `131072`, and a `600000`-element table becomes `524288` (default `prime_max`). The pool prefers
+these normalized buckets to avoid fragmentation.
+
+### Pruning
+
+The pool runs a background prune timer:
+
+- Tables idle longer than `max_idle` are discarded.
+- If `max_tables` is set, the pool removes the least-recently-used idle tables until the limit is satisfied.
+- Tables marked “in use” are never pruned.
+
+### Others
+
+Beyond `obtain()`/`_return()`, the pool exposes a few utility helpers:
+
+- `Pool.attach(tbl)`: mark a table as “in use” without placing it into the idle pool. Use this when you create a table outside
+  `obtain()` but still want the pool to track it.
+- `Pool.detach(tbl)`: remove a table from pool tracking without returning it to the idle pool.
+- `Pool.is_pooled(tbl)`: returns `true` if the table is tracked by the pool (in use or idle).
+- `Pool.fill(tbl, value)`: in-place fill of a table with a single value.
+- `Pool.resize(tbl, size, default)`: resize a table to `size`, filling new slots with `default` when expanding.
+- `Pool.remove(tbl, value)`: remove all entries that match `value` from `tbl`.
+
 ## Requirements
 
 ### Mandatory

lua/fuzzy/init.lua

@@ -1,11 +1,24 @@
 local Pool = require("fuzzy.pool")
 local Registry = require("fuzzy.registry")
 local Scheduler = require("fuzzy.scheduler")
+local group = vim.api.nvim_create_augroup("FUZZYMATCH", { clear = true })
 
 local M = {
     config = {},
 }
 
+function M.teardown()
+    if Scheduler and Scheduler.close then
+        Scheduler.close()
+    end
+    if Registry and Registry.close then
+        Registry.close()
+    end
+    if Pool and Pool.close then
+        Pool.close()
+    end
+end
+
 function M.setup(opts)
     M.config = vim.tbl_deep_extend("keep", opts or {}, {
         general = {
@@ -63,6 +76,8 @@ function M.setup(opts)
 
     vim.api.nvim_set_hl(0, "SelectLineHighlight", { link = "Normal", default = false })
     vim.api.nvim_set_hl(0, "SelectDecoratorDefault", { link = "Normal", default = false })
+
+    vim.api.nvim_create_autocmd("VimLeavePre", { group = group, callback = M.teardown() })
 end
 
 return M

lua/fuzzy/match.lua

@@ -103,7 +103,8 @@ function Match:_stop_processing()
         -- kill the timer if it is still active, this will stop any further processing, we do not wait for the current processing to finish,
         -- since it is expected that the callback will handle nil results as a signal that processing was aborted
         if vim.loop.is_closing(self._state.timer) == false then
-            pcall(vim.loop.stop, self._state.timer)
+            pcall(self._state.timer.stop, self._state.timer)
+            pcall(self._state.timer.close, self._state.timer)
         end
         self._state.timer = nil
     end
@@ -179,9 +180,11 @@ function Match:_clean_context()
     self.transform = nil
 end
 
-function Match:_bind_method(method)
+function Match:_bind_guarded(method, token)
     return function(...)
-        return method(self, ...)
+        if self._state.token == token then
+            return method(self, ...)
+        end
     end
 end
 
@@ -334,15 +337,12 @@ function Match:match(list, pattern, callback, transform)
         end
     end
 
-    -- ensure we drop the old results first, these will be re-referenced only when the matching process finishes after this matching process
-    -- that is currently being started now
-    if self.results then
-        self.results = nil
-    end
-
-    -- init core match context
+    -- version the current run, into an incrementing token, that is to ensure that older matching does not start operating on new
+    -- state or on new starts and ensures older ticks get terminated safely
     self._state.token = (self._state.token or 0) + 1
     local token = self._state.token
+
+    -- init core match context
     self.list = assert(list)
     self.pattern = assert(pattern)
     self.callback = assert(callback)
@@ -370,15 +370,22 @@ function Match:match(list, pattern, callback, transform)
     -- ensure offset restored
     self._state.offset = 0
 
+    if self.results then
+        -- ensure we drop the old results first, these will be re-referenced only when the matching process finishes after this matching process
+        -- that is currently being started now
+        self.results = nil
+    end
+
     if not self._state.accum then
-        -- prepare accumulator for results
+        -- the accumulator is an array of 3 sub-arrays, the first sub-array is the matching elements, the second is the matching
+        -- positions and the third is the score, the 3 sub-arrays are always guaranteed to be of the same size.
         self._state.accum = {}
     end
 
     if not self._state.chunks then
         -- chunks are reused to avoid frequent allocations, they represent the part of the whole source list currently being processed
         -- for matches, the chunks are first filled from the source list and then used in the matchfuzzy call
-        local size = self._options.step
+        local size = self._options.step or 0
         self._state.chunks = Pool.obtain(size)
     end
 
@@ -400,12 +407,9 @@ function Match:match(list, pattern, callback, transform)
     self._state.timer = vim.loop.new_timer()
     self._state.timer:start(0,
         self._options.timer,
-        vim.schedule_wrap(function()
-            if self._state.token ~= token then
-                return
-            end
-            Match._match_worker(self)
-        end)
+        vim.schedule_wrap(self:_bind_guarded(
+            Match._match_worker, token
+        ))
     )
 
     -- run one cycle immediately now