Struct windows_result::Error
source · pub struct Error { /* private fields */ }
Expand description
An error object consists of both an error code and optional detailed error information for debugging.
§Extended error info and the windows_slim_errors
configuration option
Error
contains an HRESULT
value that describes the error, as well as an optional
IErrorInfo
COM object. The IErrorInfo
object is a COM object that can provide detailed information
about an error, such as a text string, a ProgID
of the originator, etc. If the error object
was originated in an WinRT component, then additional information such as a stack track may be
captured.
However, many systems based on COM do not use IErrorInfo
. For these systems, the optional error
info within Error
has no benefits, but has substantial costs because it increases the size of
the Error
object, which also increases the size of Result<T>
.
This error information can be disabled at compile time by setting RUSTFLAGS=--cfg=windows_slim_errors
.
This removes the IErrorInfo
support within the Error
type, which has these benefits:
-
It reduces the size of
Error
to 4 bytes (the size ofHRESULT
). -
It reduces the size of
Result<(), Error>
to 4 bytes, allowing it to be returned in a single machine register. -
The
Error
(andResult<T, Error>
) types no longer have aDrop
impl. This removes the need for lifetime checking and running drop code whenError
andResult
go out of scope. This significantly reduces code size for codebase that make extensive use ofError
.
Of course, these benefits come with a cost; you lose extended error information for those COM objects that support it.
This is controlled by a --cfg
option rather than a Cargo feature because this compilation
option sets a policy that applies to an entire graph of crates. Individual crates that take a
dependency on the windows-result
crate are not in a good position to decide whether they want
slim errors or full errors. Cargo features are meant to be additive, but specifying the size
and contents of Error
is not a feature so much as a whole-program policy decision.
§References
Implementations§
source§impl Error
impl Error
sourcepub fn new<T: AsRef<str>>(code: HRESULT, message: T) -> Self
pub fn new<T: AsRef<str>>(code: HRESULT, message: T) -> Self
Creates a new error object, capturing the stack and other information about the point of failure.
sourcepub fn from_hresult(code: HRESULT) -> Self
pub fn from_hresult(code: HRESULT) -> Self
Creates a new error object with an error code, but without additional error information.
sourcepub fn from_win32() -> Self
pub fn from_win32() -> Self
Creates a new Error
from the Win32 error code returned by GetLastError()
.
Trait Implementations§
source§impl Error for Error
impl Error for Error
1.30.0 · source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · source§fn description(&self) -> &str
fn description(&self) -> &str
source§impl From<FromUtf16Error> for Error
impl From<FromUtf16Error> for Error
source§fn from(_: FromUtf16Error) -> Self
fn from(_: FromUtf16Error) -> Self
source§impl From<FromUtf8Error> for Error
impl From<FromUtf8Error> for Error
source§fn from(_: FromUtf8Error) -> Self
fn from(_: FromUtf8Error) -> Self
source§impl From<TryFromIntError> for Error
impl From<TryFromIntError> for Error
source§fn from(_: TryFromIntError) -> Self
fn from(_: TryFromIntError) -> Self
source§impl Ord for Error
impl Ord for Error
source§impl PartialEq for Error
impl PartialEq for Error
source§impl PartialOrd for Error
impl PartialOrd for Error
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl Eq for Error
Auto Trait Implementations§
impl Freeze for Error
impl RefUnwindSafe for Error
impl Send for Error
impl Sync for Error
impl Unpin for Error
impl UnwindSafe for Error
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)