async_std/os/windows/
io.rs

1//! Windows-specific I/O extensions.
2
3cfg_not_docs! {
4    pub use std::os::windows::io::{
5        AsRawHandle, FromRawHandle, IntoRawHandle, RawHandle,
6        AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket,
7    };
8
9    cfg_io_safety! {
10        pub use std::os::windows::io::{
11            AsHandle, BorrowedHandle, OwnedHandle,
12            AsSocket, BorrowedSocket, OwnedSocket,
13        };
14    }
15}
16
17cfg_docs! {
18    /// Raw HANDLEs.
19    pub type RawHandle = *mut std::os::raw::c_void;
20
21    /// Raw SOCKETs.
22    pub type RawSocket = u64;
23
24    /// Extracts raw handles.
25    pub trait AsRawHandle {
26        /// Extracts the raw handle, without taking any ownership.
27        fn as_raw_handle(&self) -> RawHandle;
28    }
29
30    /// Construct I/O objects from raw handles.
31    pub trait FromRawHandle {
32        /// Constructs a new I/O object from the specified raw handle.
33        ///
34        /// This function will **consume ownership** of the handle given,
35        /// passing responsibility for closing the handle to the returned
36        /// object.
37        ///
38        /// This function is also unsafe as the primitives currently returned
39        /// have the contract that they are the sole owner of the file
40        /// descriptor they are wrapping. Usage of this function could
41        /// accidentally allow violating this contract which can cause memory
42        /// unsafety in code that relies on it being true.
43        unsafe fn from_raw_handle(handle: RawHandle) -> Self;
44    }
45
46    /// A trait to express the ability to consume an object and acquire ownership of
47    /// its raw `HANDLE`.
48    pub trait IntoRawHandle {
49        /// Consumes this object, returning the raw underlying handle.
50        ///
51        /// This function **transfers ownership** of the underlying handle to the
52        /// caller. Callers are then the unique owners of the handle and must close
53        /// it once it's no longer needed.
54        fn into_raw_handle(self) -> RawHandle;
55    }
56
57    /// Creates I/O objects from raw sockets.
58    pub trait FromRawSocket {
59        /// Creates a new I/O object from the given raw socket.
60        ///
61        /// This function will consume ownership of the socket provided and it will be closed when the returned object goes out of scope.
62        ///
63        /// This function is also unsafe as the primitives currently returned have the contract that they are the sole owner of the
64        /// file descriptor they are wrapping. Usage of this function could accidentally allow violating this contract which can cause
65        /// memory unsafety in code that relies on it being true.
66        unsafe fn from_raw_socket(sock: RawSocket) -> Self;
67    }
68
69    /// Extracts raw sockets.
70    pub trait AsRawSocket {
71        /// Extracts the underlying raw socket from this object.
72        fn as_raw_socket(&self) -> RawSocket;
73    }
74
75    /// A trait to express the ability to consume an object and acquire ownership of
76    /// its raw `SOCKET`.
77    pub trait IntoRawSocket {
78        /// Consumes this object, returning the raw underlying socket.
79        ///
80        /// This function **transfers ownership** of the underlying socket to the
81        /// caller. Callers are then the unique owners of the socket and must close
82        /// it once it's no longer needed.
83        fn into_raw_socket(self) -> RawSocket;
84    }
85
86    cfg_io_safety! {
87        #[doc(inline)]
88        pub use std::os::windows::io::{
89            AsHandle, BorrowedHandle, OwnedHandle,
90            AsSocket, BorrowedSocket, OwnedSocket,
91        };
92    }
93}
async_std/os/windows/io.rs

async_std/os/windows/
io.rs
