1 //! Windows-specific extensions to general I/O primitives.
3 //! Just like raw pointers, raw Windows handles and sockets point to resources
4 //! with dynamic lifetimes, and they can dangle if they outlive their resources
5 //! or be forged if they're created from invalid values.
7 //! This module provides three types for representing raw handles and sockets
8 //! with different ownership properties: raw, borrowed, and owned, which are
9 //! analogous to types used for representing pointers:
11 //! | Type | Analogous to |
12 //! | ---------------------- | ------------ |
13 //! | [`RawHandle`] | `*const _` |
14 //! | [`RawSocket`] | `*const _` |
16 //! | [`BorrowedHandle<'a>`] | `&'a _` |
17 //! | [`BorrowedSocket<'a>`] | `&'a _` |
19 //! | [`OwnedHandle`] | `Box<_>` |
20 //! | [`OwnedSocket`] | `Box<_>` |
22 //! Like raw pointers, `RawHandle` and `RawSocket` values are primitive values.
23 //! And in new code, they should be considered unsafe to do I/O on (analogous
24 //! to dereferencing them). Rust did not always provide this guidance, so
25 //! existing code in the Rust ecosystem often doesn't mark `RawHandle` and
26 //! `RawSocket` usage as unsafe. Once the `io_safety` feature is stable,
27 //! libraries will be encouraged to migrate, either by adding `unsafe` to APIs
28 //! that dereference `RawHandle` and `RawSocket` values, or by using to
29 //! `BorrowedHandle`, `BorrowedSocket`, `OwnedHandle`, or `OwnedSocket`.
31 //! Like references, `BorrowedHandle` and `BorrowedSocket` values are tied to a
32 //! lifetime, to ensure that they don't outlive the resource they point to.
33 //! These are safe to use. `BorrowedHandle` and `BorrowedSocket` values may be
34 //! used in APIs which provide safe access to any system call except for
35 //! `CloseHandle`, `closesocket`, or any other call that would end the
36 //! dynamic lifetime of the resource without ending the lifetime of the
39 //! Like boxes, `OwnedHandle` and `OwnedSocket` values conceptually own the
40 //! resource they point to, and free (close) it when they are dropped.
42 //! [`BorrowedHandle<'a>`]: crate::os::windows::io::BorrowedHandle
43 //! [`BorrowedSocket<'a>`]: crate::os::windows::io::BorrowedSocket
45 #![stable(feature = "rust1", since = "1.0.0")]
51 #[unstable(feature = "io_safety", issue = "87074")]
53 #[stable(feature = "rust1", since = "1.0.0")]
55 #[unstable(feature = "io_safety", issue = "87074")]