| <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Source of the Rust file `/root/.cargo/registry/src/github.com-1ecc6299db9ec823/socket2-0.4.9/src/sockref.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>sockref.rs - source</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../../normalize.css"><link rel="stylesheet" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../../ayu.css" disabled><link rel="stylesheet" href="../../dark.css" disabled><link rel="stylesheet" href="../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../storage.js"></script><script defer src="../../source-script.js"></script><script defer src="../../source-files.js"></script><script defer src="../../main.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../../favicon.svg"></head><body class="rustdoc source"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><a class="sidebar-logo" href="../../socket2/index.html"><div class="logo-container"><img class="rust-logo" src="../../rust-logo.svg" alt="logo"></div></a></nav><main><div class="width-limiter"><nav class="sub"><a class="sub-logo-container" href="../../socket2/index.html"><img class="rust-logo" src="../../rust-logo.svg" alt="logo"></a><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="example-wrap"><pre class="src-line-numbers"><span id="1">1</span> |
| <span id="2">2</span> |
| <span id="3">3</span> |
| <span id="4">4</span> |
| <span id="5">5</span> |
| <span id="6">6</span> |
| <span id="7">7</span> |
| <span id="8">8</span> |
| <span id="9">9</span> |
| <span id="10">10</span> |
| <span id="11">11</span> |
| <span id="12">12</span> |
| <span id="13">13</span> |
| <span id="14">14</span> |
| <span id="15">15</span> |
| <span id="16">16</span> |
| <span id="17">17</span> |
| <span id="18">18</span> |
| <span id="19">19</span> |
| <span id="20">20</span> |
| <span id="21">21</span> |
| <span id="22">22</span> |
| <span id="23">23</span> |
| <span id="24">24</span> |
| <span id="25">25</span> |
| <span id="26">26</span> |
| <span id="27">27</span> |
| <span id="28">28</span> |
| <span id="29">29</span> |
| <span id="30">30</span> |
| <span id="31">31</span> |
| <span id="32">32</span> |
| <span id="33">33</span> |
| <span id="34">34</span> |
| <span id="35">35</span> |
| <span id="36">36</span> |
| <span id="37">37</span> |
| <span id="38">38</span> |
| <span id="39">39</span> |
| <span id="40">40</span> |
| <span id="41">41</span> |
| <span id="42">42</span> |
| <span id="43">43</span> |
| <span id="44">44</span> |
| <span id="45">45</span> |
| <span id="46">46</span> |
| <span id="47">47</span> |
| <span id="48">48</span> |
| <span id="49">49</span> |
| <span id="50">50</span> |
| <span id="51">51</span> |
| <span id="52">52</span> |
| <span id="53">53</span> |
| <span id="54">54</span> |
| <span id="55">55</span> |
| <span id="56">56</span> |
| <span id="57">57</span> |
| <span id="58">58</span> |
| <span id="59">59</span> |
| <span id="60">60</span> |
| <span id="61">61</span> |
| <span id="62">62</span> |
| <span id="63">63</span> |
| <span id="64">64</span> |
| <span id="65">65</span> |
| <span id="66">66</span> |
| <span id="67">67</span> |
| <span id="68">68</span> |
| <span id="69">69</span> |
| <span id="70">70</span> |
| <span id="71">71</span> |
| <span id="72">72</span> |
| <span id="73">73</span> |
| <span id="74">74</span> |
| <span id="75">75</span> |
| <span id="76">76</span> |
| <span id="77">77</span> |
| <span id="78">78</span> |
| <span id="79">79</span> |
| <span id="80">80</span> |
| <span id="81">81</span> |
| <span id="82">82</span> |
| <span id="83">83</span> |
| <span id="84">84</span> |
| <span id="85">85</span> |
| <span id="86">86</span> |
| <span id="87">87</span> |
| <span id="88">88</span> |
| <span id="89">89</span> |
| <span id="90">90</span> |
| <span id="91">91</span> |
| <span id="92">92</span> |
| <span id="93">93</span> |
| <span id="94">94</span> |
| <span id="95">95</span> |
| <span id="96">96</span> |
| <span id="97">97</span> |
| <span id="98">98</span> |
| <span id="99">99</span> |
| <span id="100">100</span> |
| <span id="101">101</span> |
| <span id="102">102</span> |
| <span id="103">103</span> |
| <span id="104">104</span> |
| <span id="105">105</span> |
| <span id="106">106</span> |
| <span id="107">107</span> |
| <span id="108">108</span> |
| <span id="109">109</span> |
| <span id="110">110</span> |
| <span id="111">111</span> |
| <span id="112">112</span> |
| <span id="113">113</span> |
| <span id="114">114</span> |
| <span id="115">115</span> |
| <span id="116">116</span> |
| <span id="117">117</span> |
| <span id="118">118</span> |
| <span id="119">119</span> |
| <span id="120">120</span> |
| <span id="121">121</span> |
| <span id="122">122</span> |
| <span id="123">123</span> |
| <span id="124">124</span> |
| <span id="125">125</span> |
| <span id="126">126</span> |
| <span id="127">127</span> |
| <span id="128">128</span> |
| <span id="129">129</span> |
| <span id="130">130</span> |
| <span id="131">131</span> |
| <span id="132">132</span> |
| <span id="133">133</span> |
| <span id="134">134</span> |
| <span id="135">135</span> |
| <span id="136">136</span> |
| <span id="137">137</span> |
| <span id="138">138</span> |
| <span id="139">139</span> |
| <span id="140">140</span> |
| <span id="141">141</span> |
| <span id="142">142</span> |
| <span id="143">143</span> |
| <span id="144">144</span> |
| <span id="145">145</span> |
| <span id="146">146</span> |
| <span id="147">147</span> |
| </pre><pre class="rust"><code><span class="kw">use </span>std::fmt; |
| <span class="kw">use </span>std::marker::PhantomData; |
| <span class="kw">use </span>std::mem::ManuallyDrop; |
| <span class="kw">use </span>std::ops::Deref; |
| <span class="attribute">#[cfg(unix)] |
| </span><span class="kw">use </span>std::os::unix::io::{AsRawFd, FromRawFd}; |
| <span class="attribute">#[cfg(windows)] |
| </span><span class="kw">use </span>std::os::windows::io::{AsRawSocket, FromRawSocket}; |
| |
| <span class="kw">use </span><span class="kw">crate</span>::Socket; |
| |
| <span class="doccomment">/// A reference to a [`Socket`] that can be used to configure socket types other |
| /// than the `Socket` type itself. |
| /// |
| /// This allows for example a [`TcpStream`], found in the standard library, to |
| /// be configured using all the additional methods found in the [`Socket`] API. |
| /// |
| /// `SockRef` can be created from any socket type that implements [`AsRawFd`] |
| /// (Unix) or [`AsRawSocket`] (Windows) using the [`From`] implementation, but |
| /// the caller must ensure the file descriptor/socket is a valid. |
| /// |
| /// [`TcpStream`]: std::net::TcpStream |
| </span><span class="comment">// Don't use intra-doc links because they won't build on every platform. |
| </span><span class="doccomment">/// [`AsRawFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/trait.AsRawFd.html |
| /// [`AsRawSocket`]: https://doc.rust-lang.org/stable/std/os/windows/io/trait.AsRawSocket.html |
| /// |
| /// # Examples |
| /// |
| /// Below is an example of converting a [`TcpStream`] into a [`SockRef`]. |
| /// |
| /// ``` |
| /// use std::net::{TcpStream, SocketAddr}; |
| /// |
| /// use socket2::SockRef; |
| /// |
| /// # fn main() -> Result<(), Box<dyn std::error::Error>> { |
| /// // Create `TcpStream` from the standard library. |
| /// let address: SocketAddr = "127.0.0.1:1234".parse()?; |
| /// # let b1 = std::sync::Arc::new(std::sync::Barrier::new(2)); |
| /// # let b2 = b1.clone(); |
| /// # let handle = std::thread::spawn(move || { |
| /// # let listener = std::net::TcpListener::bind(address).unwrap(); |
| /// # b2.wait(); |
| /// # let (stream, _) = listener.accept().unwrap(); |
| /// # std::thread::sleep(std::time::Duration::from_millis(10)); |
| /// # drop(stream); |
| /// # }); |
| /// # b1.wait(); |
| /// let stream = TcpStream::connect(address)?; |
| /// |
| /// // Create a `SockRef`erence to the stream. |
| /// let socket_ref = SockRef::from(&stream); |
| /// // Use `Socket::set_nodelay` on the stream. |
| /// socket_ref.set_nodelay(true)?; |
| /// drop(socket_ref); |
| /// |
| /// assert_eq!(stream.nodelay()?, true); |
| /// # handle.join().unwrap(); |
| /// # Ok(()) |
| /// # } |
| /// ``` |
| /// |
| /// Below is an example of **incorrect usage** of `SockRef::from`, which is |
| /// currently possible (but not intended and will be fixed in future versions). |
| /// |
| /// ```compile_fail |
| /// use socket2::SockRef; |
| /// |
| /// # fn main() -> Result<(), Box<dyn std::error::Error>> { |
| /// /// THIS USAGE IS NOT VALID! |
| /// let socket_ref = SockRef::from(&123); |
| /// // The above line is overseen possibility when using `SockRef::from`, it |
| /// // uses the `RawFd` (on Unix), which is a type alias for `c_int`/`i32`, |
| /// // which implements `AsRawFd`. However it may be clear that this usage is |
| /// // invalid as it doesn't guarantee that `123` is a valid file descriptor. |
| /// |
| /// // Using `Socket::set_nodelay` now will call it on a file descriptor we |
| /// // don't own! We don't even not if the file descriptor is valid or a socket. |
| /// socket_ref.set_nodelay(true)?; |
| /// drop(socket_ref); |
| /// # Ok(()) |
| /// # } |
| /// # DO_NOT_COMPILE |
| /// ``` |
| </span><span class="kw">pub struct </span>SockRef<<span class="lifetime">'s</span>> { |
| <span class="doccomment">/// Because this is a reference we don't own the `Socket`, however `Socket` |
| /// closes itself when dropped, so we use `ManuallyDrop` to prevent it from |
| /// closing itself. |
| </span>socket: ManuallyDrop<Socket>, |
| <span class="doccomment">/// Because we don't own the socket we need to ensure the socket remains |
| /// open while we have a "reference" to it, the lifetime `'s` ensures this. |
| </span>_lifetime: PhantomData<<span class="kw-2">&</span><span class="lifetime">'s </span>Socket>, |
| } |
| |
| <span class="kw">impl</span><<span class="lifetime">'s</span>> Deref <span class="kw">for </span>SockRef<<span class="lifetime">'s</span>> { |
| <span class="kw">type </span>Target = Socket; |
| |
| <span class="kw">fn </span>deref(<span class="kw-2">&</span><span class="self">self</span>) -> <span class="kw-2">&</span><span class="self">Self</span>::Target { |
| <span class="kw-2">&</span><span class="self">self</span>.socket |
| } |
| } |
| |
| <span class="doccomment">/// On Windows, a corresponding `From<&impl AsRawSocket>` implementation exists. |
| </span><span class="attribute">#[cfg(unix)] |
| #[cfg_attr(docsrs, doc(cfg(unix)))] |
| </span><span class="kw">impl</span><<span class="lifetime">'s</span>, S> From<<span class="kw-2">&</span><span class="lifetime">'s </span>S> <span class="kw">for </span>SockRef<<span class="lifetime">'s</span>> |
| <span class="kw">where |
| </span>S: AsRawFd, |
| { |
| <span class="doccomment">/// The caller must ensure `S` is actually a socket. |
| </span><span class="kw">fn </span>from(socket: <span class="kw-2">&</span><span class="lifetime">'s </span>S) -> <span class="self">Self </span>{ |
| <span class="kw">let </span>fd = socket.as_raw_fd(); |
| <span class="macro">assert!</span>(fd >= <span class="number">0</span>); |
| SockRef { |
| socket: ManuallyDrop::new(<span class="kw">unsafe </span>{ Socket::from_raw_fd(fd) }), |
| _lifetime: PhantomData, |
| } |
| } |
| } |
| |
| <span class="doccomment">/// On Unix, a corresponding `From<&impl AsRawFd>` implementation exists. |
| </span><span class="attribute">#[cfg(windows)] |
| #[cfg_attr(docsrs, doc(cfg(windows)))] |
| </span><span class="kw">impl</span><<span class="lifetime">'s</span>, S> From<<span class="kw-2">&</span><span class="lifetime">'s </span>S> <span class="kw">for </span>SockRef<<span class="lifetime">'s</span>> |
| <span class="kw">where |
| </span>S: AsRawSocket, |
| { |
| <span class="doccomment">/// See the `From<&impl AsRawFd>` implementation. |
| </span><span class="kw">fn </span>from(socket: <span class="kw-2">&</span><span class="lifetime">'s </span>S) -> <span class="self">Self </span>{ |
| <span class="kw">let </span>socket = socket.as_raw_socket(); |
| <span class="macro">assert!</span>(socket != winapi::um::winsock2::INVALID_SOCKET <span class="kw">as _</span>); |
| SockRef { |
| socket: ManuallyDrop::new(<span class="kw">unsafe </span>{ Socket::from_raw_socket(socket) }), |
| _lifetime: PhantomData, |
| } |
| } |
| } |
| |
| <span class="kw">impl </span>fmt::Debug <span class="kw">for </span>SockRef<<span class="lifetime">'_</span>> { |
| <span class="kw">fn </span>fmt(<span class="kw-2">&</span><span class="self">self</span>, f: <span class="kw-2">&mut </span>fmt::Formatter<<span class="lifetime">'_</span>>) -> fmt::Result { |
| f.debug_struct(<span class="string">"SockRef"</span>) |
| .field(<span class="string">"raw"</span>, <span class="kw-2">&</span><span class="self">self</span>.socket.as_raw()) |
| .field(<span class="string">"local_addr"</span>, <span class="kw-2">&</span><span class="self">self</span>.socket.local_addr().ok()) |
| .field(<span class="string">"peer_addr"</span>, <span class="kw-2">&</span><span class="self">self</span>.socket.peer_addr().ok()) |
| .finish() |
| } |
| } |
| </code></pre></div> |
| </section></div></main><div id="rustdoc-vars" data-root-path="../../" data-current-crate="socket2" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |