RONCC
/
HPC-Tools-for-Quantum-Computing


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211
							<!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="API documentation for the Rust `UnsafeNotify` trait in crate `futures`.">
    <meta name="keywords" content="rust, rustlang, rust-lang, UnsafeNotify">

    <title>futures::executor::UnsafeNotify - Rust</title>

    <link rel="stylesheet" type="text/css" href="../../normalize.css">
    <link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle">
    
    <link rel="stylesheet" type="text/css" href="../../dark.css">
    <link rel="stylesheet" type="text/css" href="../../main.css" id="themeStyle">
    <script src="../../storage.js"></script>
    

    
    
</head>
<body class="rustdoc trait">
    <!--[if lte IE 8]>
    <div class="warning">
        This old browser is unsupported and will most likely display funky
        things.
    </div>
    <![endif]-->

    

    <nav class="sidebar">
        <div class="sidebar-menu">&#9776;</div>
        
        <p class='location'>Trait UnsafeNotify</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#required-methods">Required Methods</a><div class="sidebar-links"><a href="#tymethod.clone_raw">clone_raw</a><a href="#tymethod.drop_raw">drop_raw</a></div><a class="sidebar-title" href="#implementors">Implementors</a></div><p class='location'><a href='../index.html'>futures</a>::<wbr><a href='index.html'>executor</a></p><script>window.sidebarCurrent = {name: 'UnsafeNotify', ty: 'trait', relpath: ''};</script><script defer src="sidebar-items.js"></script></div>
    </nav>

    <div class="theme-picker">
        <button id="theme-picker" aria-label="Pick another theme!">
            <img src="../../brush.svg" width="18" alt="Pick another theme!">
        </button>
        <div id="theme-choices"></div>
    </div>
    <script src="../../theme.js"></script>
    <nav class="sub">
        <form class="search-form js-only">
            <div class="search-container">
                <input class="search-input" name="search"
                       autocomplete="off"
                       placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
                       type="search">
            </div>
        </form>
    </nav>

    <section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Trait <a href='../index.html'>futures</a>::<wbr><a href='index.html'>executor</a>::<wbr><a class="trait" href=''>UnsafeNotify</a></span><span class='out-of-band'><span id='render-detail'>
                   <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                       [<span class='inner'>&#x2212;</span>]
                   </a>
               </span><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#530-572' title='goto source code'>[src]</a></span></h1>
<pre class='rust trait'>pub unsafe trait UnsafeNotify: <a class="trait" href="../../futures/executor/trait.Notify.html" title="trait futures::executor::Notify">Notify</a> {
    unsafe fn <a href='#tymethod.clone_raw' class='fnname'>clone_raw</a>(&amp;self) -&gt; <a class="struct" href="../../futures/executor/struct.NotifyHandle.html" title="struct futures::executor::NotifyHandle">NotifyHandle</a>;
<div class='item-spacer'></div>    unsafe fn <a href='#tymethod.drop_raw' class='fnname'>drop_raw</a>(&amp;self);
}</pre><div class='docblock'><p>An unsafe trait for implementing custom forms of memory management behind a
<code>Task</code>.</p>
<p>The <code>futures</code> critically relies on &quot;notification handles&quot; to extract for
futures to contain and then later inform that they're ready to make
progress. These handles, however, must be cheap to create and cheap
to clone to ensure that this operation is efficient throughout the
execution of a program.</p>
<p>Typically this sort of memory management is done in the standard library
with the <code>Arc</code> type. An <code>Arc</code> is relatively cheap to allocate an is
quite cheap to clone and pass around. Plus, it's 100% safe!</p>
<p>When working outside the standard library, however, you don't always have
and <code>Arc</code> type available to you. This trait, <code>UnsafeNotify</code>, is intended
to be the &quot;unsafe version&quot; of the <code>Notify</code> trait. This trait encodes the
memory management operations of a <code>Task</code>'s notification handle, allowing
custom implementations for the memory management of a notification handle.</p>
<p>Put another way, the core notification type in this library,
<code>NotifyHandle</code>, simply internally contains an instance of
<code>*mut UnsafeNotify</code>. This &quot;unsafe trait object&quot; is then used exclusively
to operate with, dynamically dispatching calls to clone, drop, and notify.
Critically though as a raw pointer it doesn't require a particular form
of memory management, allowing external implementations.</p>
<p>A default implementation of the <code>UnsafeNotify</code> trait is provided for the
<code>Arc</code> type in the standard library. If the <code>use_std</code> feature of this crate
is not available however, you'll be required to implement your own
instance of this trait to pass it into <code>NotifyHandle::new</code>.</p>
<h1 id="unsafety" class="section-header"><a href="#unsafety">Unsafety</a></h1>
<p>This trait is manually encoding the memory management of the underlying
handle, and as a result is quite unsafe to implement! Implementors of
this trait must guarantee:</p>
<ul>
<li>Calls to <code>clone_raw</code> produce uniquely owned handles. It should be safe
to drop the current handle and have the returned handle still be valid.</li>
<li>Calls to <code>drop_raw</code> work with <code>self</code> as a raw pointer, deallocating
resources associated with it. This is a pretty unsafe operation as it's
invalidating the <code>self</code> pointer, so extreme care needs to be taken.</li>
</ul>
<p>In general it's recommended to review the trait documentation as well as
the implementation for <code>Arc</code> in this crate. When in doubt ping the
<code>futures</code> authors to clarify an unsafety question here.</p>
</div>
            <h2 id='required-methods' class='small-section-header'>
              Required Methods<a href='#required-methods' class='anchor'></a>
            </h2>
            <div class='methods'>
        <h3 id='tymethod.clone_raw' class='method'><span id='clone_raw.v' class='invisible'><code>unsafe fn <a href='#tymethod.clone_raw' class='fnname'>clone_raw</a>(&amp;self) -&gt; <a class="struct" href="../../futures/executor/struct.NotifyHandle.html" title="struct futures::executor::NotifyHandle">NotifyHandle</a></code></span></h3><div class='docblock'><p>Creates a new <code>NotifyHandle</code> from this instance of <code>UnsafeNotify</code>.</p>
<p>This function will create a new uniquely owned handle that under the
hood references the same notification instance. In other words calls
to <code>notify</code> on the returned handle should be equivalent to calls to
<code>notify</code> on this handle.</p>
<h1 id="unsafety-1" class="section-header"><a href="#unsafety-1">Unsafety</a></h1>
<p>This trait is unsafe to implement, as are all these methods. This
method is also unsafe to call as it's asserting the <code>UnsafeNotify</code>
value is in a consistent state. In general it's recommended to
review the trait documentation as well as the implementation for <code>Arc</code>
in this crate. When in doubt ping the <code>futures</code> authors to clarify
an unsafety question here.</p>
</div><h3 id='tymethod.drop_raw' class='method'><span id='drop_raw.v' class='invisible'><code>unsafe fn <a href='#tymethod.drop_raw' class='fnname'>drop_raw</a>(&amp;self)</code></span></h3><div class='docblock'><p>Drops this instance of <code>UnsafeNotify</code>, deallocating resources
associated with it.</p>
<p>This method is intended to have a signature such as:</p>

<div class='information'><div class='tooltip ignore'>ⓘ<span class='tooltiptext'>This example is not tested</span></div></div><pre class="rust rust-example-rendered ignore">
<span class="kw">fn</span> <span class="ident">drop_raw</span>(<span class="self">self</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="self">Self</span>);</pre>
<p>Unfortunately in Rust today that signature is not object safe.
Nevertheless it's recommended to implement this function <em>as if</em> that
were its signature. As such it is not safe to call on an invalid
pointer, nor is the validity of the pointer guaranteed after this
function returns.</p>
<h1 id="unsafety-2" class="section-header"><a href="#unsafety-2">Unsafety</a></h1>
<p>This trait is unsafe to implement, as are all these methods. This
method is also unsafe to call as it's asserting the <code>UnsafeNotify</code>
value is in a consistent state. In general it's recommended to
review the trait documentation as well as the implementation for <code>Arc</code>
in this crate. When in doubt ping the <code>futures</code> authors to clarify
an unsafety question here.</p>
</div></div>
        <h2 id='implementors' class='small-section-header'>
          Implementors<a href='#implementors' class='anchor'></a>
        </h2>
        <ul class='item-list' id='implementors-list'>
    </ul><script type="text/javascript" async
                         src="../../implementors/futures/executor/trait.UnsafeNotify.js">
                 </script></section>
    <section id='search' class="content hidden"></section>

    <section class="footer"></section>

    <aside id="help" class="hidden">
        <div>
            <h1 class="hidden">Help</h1>

            <div class="shortcuts">
                <h2>Keyboard Shortcuts</h2>

                <dl>
                    <dt><kbd>?</kbd></dt>
                    <dd>Show this help dialog</dd>
                    <dt><kbd>S</kbd></dt>
                    <dd>Focus the search field</dd>
                    <dt><kbd>↑</kbd></dt>
                    <dd>Move up in search results</dd>
                    <dt><kbd>↓</kbd></dt>
                    <dd>Move down in search results</dd>
                    <dt><kbd>↹</kbd></dt>
                    <dd>Switch tab</dd>
                    <dt><kbd>&#9166;</kbd></dt>
                    <dd>Go to active search result</dd>
                    <dt><kbd>+</kbd></dt>
                    <dd>Expand all sections</dd>
                    <dt><kbd>-</kbd></dt>
                    <dd>Collapse all sections</dd>
                </dl>
            </div>

            <div class="infos">
                <h2>Search Tricks</h2>

                <p>
                    Prefix searches with a type followed by a colon (e.g.
                    <code>fn:</code>) to restrict the search to a given type.
                </p>

                <p>
                    Accepted types are: <code>fn</code>, <code>mod</code>,
                    <code>struct</code>, <code>enum</code>,
                    <code>trait</code>, <code>type</code>, <code>macro</code>,
                    and <code>const</code>.
                </p>

                <p>
                    Search functions by type signature (e.g.
                    <code>vec -> usize</code> or <code>* -> vec</code>)
                </p>
            </div>
        </div>
    </aside>

    

    <script>
        window.rootPath = "../../";
        window.currentCrate = "futures";
    </script>
    <script src="../../main.js"></script>
    <script defer src="../../search-index.js"></script>
</body>
</html>