library/std/src/os/windows/io/mod.rs

   1 //! Windows-specific extensions to general I/O primitives.
   2 //!
   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.
   6 //!
   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:
  10 //!
  11 //! | Type                   | Analogous to |
  12 //! | ---------------------- | ------------ |
  13 //! | [`RawHandle`]          | `*const _`   |
  14 //! | [`RawSocket`]          | `*const _`   |
  15 //! |                        |              |
  16 //! | [`BorrowedHandle<'a>`] | `&'a _`      |
  17 //! | [`BorrowedSocket<'a>`] | `&'a _`      |
  18 //! |                        |              |
  19 //! | [`OwnedHandle`]        | `Box<_>`     |
  20 //! | [`OwnedSocket`]        | `Box<_>`     |
  21 //!
  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`.
  30 //!
  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
  37 //! handle or socket.
  38 //!
  39 //! Like boxes, `OwnedHandle` and `OwnedSocket` values conceptually own the
  40 //! resource they point to, and free (close) it when they are dropped.
  41 //!
  42 //! [`BorrowedHandle<'a>`]: crate::os::windows::io::BorrowedHandle
  43 //! [`BorrowedSocket<'a>`]: crate::os::windows::io::BorrowedSocket
  44
  45 #![stable(feature = "rust1", since = "1.0.0")]
  46
  47 mod handle;
  48 mod raw;
  49 mod socket;
  50
  51 #[unstable(feature = "io_safety", issue = "87074")]
  52 pub use handle::*;
  53 #[stable(feature = "rust1", since = "1.0.0")]
  54 pub use raw::*;
  55 #[unstable(feature = "io_safety", issue = "87074")]
  56 pub use socket::*;