Expand description
The seam: what every entry has in common, as a trait.
Each entry is already a value whose perform is the single point where
Win32 is touched. This module adds the trait over that, so a consumer’s code
can be written against “a request that produces T” rather than against a
concrete entry – and can therefore be exercised in that consumer’s own
tests without a filesystem, a network path, or a device that may not be
present.
§Why two traits rather than one
The distinction is real, not cosmetic. An open is a parameter set: it
may be performed repeatedly, producing an independent handle each time, so
it takes &self. A close is one-shot: performing it consumes the
request, which is what makes closing twice through this crate impossible.
Collapsing them into one trait would have to pick a side, and both choices
lie. A &self trait would make a close look repeatable; a self trait would
make every open look single-use and force a caller to rebuild a request it
could simply have performed again.
§Why the error type is an associated type
Most entries fail only as Windows failed, so their error is a
Win32Error. Two do not:
crate::final_path::QueryFinalPath and
crate::full_path::ResolveFullPath each retry a growing buffer, and “the
required size kept changing” is a failure Win32 has no code for. They report
it as FinalPathError::Unstable and
FullPathError::Unstable respectively.
Fixing the trait’s error to Win32Error would have left those entries
outside the seam, which would make the seam not level – a consumer could
substitute a fake for some entries and not the rest. An associated Error
keeps every entry reachable through one trait without any of them having to
invent a code it does not have.
That last clause is load-bearing rather than decorative. ResolveFullPath
did invent one for a while, returning a synthesized
ERROR_INSUFFICIENT_BUFFER that Win32 can also produce by itself, so a
caller could not tell the crate’s own retry giving up from a genuine Windows
failure. The rule stated here is what the entry now follows.
§This is a seam, not an abstraction layer
The traits exist so a consumer can substitute a fake. They are not a
plug-in point for alternative implementations of Windows, and nothing in
this crate dispatches through them: the entries keep their inherent
perform methods, which is what an ordinary caller uses.
Traits§
- Consuming
Request - A request that is consumed by performing it.
- Request
- A request that may be performed more than once.