Expand description
globazog — a high-performance, Windows-first globbing and directory-traversal
library.
A query is a set of glob patterns over a set of roots (D-36). You build one
with QueryBuilder, call submit, and service the
resulting completion ring: matches, container enter/end markers, per-entry
errors, and a final terminal marker all arrive as CqItems in delivery order.
The walk runs on a permit-bounded pool of background threads (D-3); the client’s
drain rate is the backpressure throttle (D-11).
use globazog::{CqItem, Dialect, QueryBuilder};
// Every `*.rs` under the current directory, recursively. Roots must be absolute
// (D-74), so resolve the CWD at your edge.
let handle = QueryBuilder::new()
.root(std::env::current_dir().expect("current dir"))
.pattern("**/*.rs", Dialect::Posix, Vec::new())
.submit()
.expect("valid query");
let ring = handle.completions();
loop {
match ring.wait_pop() {
CqItem::Match(m) => println!("match: {}", m.name.to_string_lossy()),
CqItem::Terminal(_) => break,
_ => {}
}
}§Servicing the completion ring
QueryHandle::completions gives you the CompletionRing. Pop items with
wait_pop (blocking), pop
(non-blocking), or drain (all queued), and keep going
until a CqItem::Terminal arrives — it is always the last item. The variants:
CqItem::Match— an entry matched.Match::nameis the entry name,Match::matchedis aPatternMaskwhose.iter()yields the indices of the patterns that matched (in the order they were added), andMatch::metacarries the requested size / timestamps / type.CqItem::ContainerEnter/CqItem::ContainerEnd— a directory scan started / its subtree finished. Ends cascade bottom-up and are 1:1 with their enters — every enter gets an end before the terminal, including on cancellation or a fatal error — and an enter always precedes anyMatchor child that references it.CqItem::Error— a per-entry or per-directory failure (e.g. permission denied, or an entry that vanished mid-scan); the walk continues past it (D-53). A single unreadable entry never discards its readable siblings.CqItem::Blocked— underconfine_to_roots, a followed reparse point (symlink / junction) was not descended because its real target resolves outside the query roots, or could not be resolved (fail-closed); the walk continues (D-75).CqItem::Terminal— the walk ended:Completed(ran to the end),Cancelled(acancelwas honored), orFailed(a fatal error — currently a root that could not be enumerated — stopped the walk; the causing error is theCqItem::Errorimmediately before this terminal, D-71).
Full paths are not shipped per entry; reconstruct them client-side by keeping a
container id → (parent, name) map from the ContainerEnter stream and
walking to the root (a ContainerName::Root carries the root’s index, which
QueryHandle::roots resolves to a path — including the internally derived root
of a self-rooting pattern). For a flat listing you often only need
Match::name, as the example above shows.
§Filtering, backpressure, and cancellation
Each pattern takes a per-pattern emit filter (the third argument to
pattern) and the query takes one descend filter
(descend); both are AND-only conjunctions of Leaf
conditions evaluated inline. The ring is bounded and never drops — a slow
consumer simply throttles the walk (D-11). QueryHandle::cancel stops early:
you still get a terminal after the already-queued items — Cancelled when the
request is honored before the walk finishes, or Completed if the cancel lost the
race with normal completion (so a Completed after a cancel() is not a
contract violation). Dropping the handle cancels and joins the engine threads. See
Options to tune the permit count, ring capacity, cycle detection, the
follow_links reparse policy, and confine_to_roots (keep a followed link from
escaping the roots, D-75).
§Dialects and brace escaping (D-45)
Patterns are parsed in a named Dialect. Dialect::Posix uses /
separators and \ escapes; Dialect::Win uses both / and \ as separators
(so \ cannot escape) and instead escapes a literal brace by doubling it:
{{ means a literal { and }} means a literal }, while a single {a,b} is
alternation. For example, the win pattern logs\{{2026}}\*.txt matches files
in a directory literally named {2026}.
§Design
The full design is recorded in DESIGN-NOTES.md at the repository root; each
module’s docs cite the relevant decision IDs (D-n), and the engine’s model is
decision D-70.
Re-exports§
pub use builder::FollowLinks;pub use builder::Options;pub use builder::PatternEntry;pub use builder::Query;pub use builder::QueryBuilder;pub use builder::QueryHandle;pub use builder::Root;pub use error::EntryError;pub use error::Error;pub use predicate::Cmp;pub use predicate::EntryType;pub use predicate::Leaf;pub use predicate::MetaMask;pub use predicate::TimeField;pub use ring::BlockReason;pub use ring::Blocked;pub use ring::CompletionRing;pub use ring::ContainerEnd;pub use ring::ContainerEnter;pub use ring::ContainerId;pub use ring::ContainerName;pub use ring::CqError;pub use ring::CqItem;pub use ring::Decision;pub use ring::DecisionRequest;pub use ring::DecisionToken;pub use ring::EntryMetaOwned;pub use ring::Match;pub use ring::Name;pub use ring::PatternMask;pub use ring::SubmissionQueue;pub use ring::Terminal;pub use ring::TerminalReason;pub use syntax::CaseSensitivity;pub use syntax::dialect::Dialect;
Modules§
- builder
- The public query builder (D-31–D-34): accepts absolute patterns / a CWD base and
lowers to the core query-def (roots + relative patterns) consumed by the engine;
submitcompiles the pattern set (D-66). - error
- Error taxonomy: the fatal crate error, and the per-entry error item surfaced in the output stream rather than aborting the walk (D-53).
- predicate
- Declarative predicates (D-56, D-66): an AND-only vocabulary of signed / set-
membership
Leafconditions over entry metadata, a flat-conjunction evaluator (D-67), and the lazy-statxfetch-mask (D-62). Emit predicates are per-pattern and descend predicates are per-query; their composition with the glob set (D-66) is performed by the engine (M6/M7). Name conditions reuse the single-segment matcher (M2), so they honor the same case rules. - ring
- The io_uring-shaped submit/complete API (D-55): the SQ op set (D-66), the CQ
item enum (Match / ContainerEnter / ContainerEnd / Error / DecisionRequest /
Terminal — D-64) on a bounded MPMC ring (D-68) with park/wake backpressure
(D-11) and a waitable-handle +
drainservicing surface (D-60); cancellation (D-61); Rust-native ABI (D-65). - syntax
- Glob syntax: the closed set of named dialects (D-15–D-20), each a front-end that
lowers a UTF-8 pattern into the shared segment-structured IR (D-18); the matcher
over 32-bit code points (D-46) with
*/**/?/ n-ary brace alternation (D-24, D-44, D-67); anchor extraction and the pattern-set model (D-36–D-39). - sys
- Platform layer (D-54).
enumeratedispatches to the native synchronous backend on Windows (GetFileInformationByHandleEx— D-4) and Linux (getdents64+statx— D-6), and falls back to the portable reference backend (enumerate_dir, safestd::fs) on other platforms. This module also provides thesignalwaitable primitive. The completion-based enumeration abstraction (D-5) and the overlapped/async OS paths (Windows overlappedNtQueryDirectoryFile+ IOCP, Linux io_uring) remain sequenced follow-ups (see CHECKLIST.md M7-6).