RONCC
/
HPC-Tools-for-Quantum-Computing


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
							<!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 `BufferReadCmd` struct in crate `ocl`.">
    <meta name="keywords" content="rust, rustlang, rust-lang, BufferReadCmd">

    <title>ocl::builders::BufferReadCmd - 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 struct">
    <!--[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'>Struct BufferReadCmd</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.queue">queue</a><a href="#method.block">block</a><a href="#method.offset">offset</a><a href="#method.dst_offset">dst_offset</a><a href="#method.len">len</a><a href="#method.rect">rect</a><a href="#method.ewait">ewait</a><a href="#method.enew">enew</a><a href="#method.enq">enq</a><a href="#method.enq_async">enq_async</a></div></div><p class='location'><a href='../index.html'>ocl</a>::<wbr><a href='index.html'>builders</a></p><script>window.sidebarCurrent = {name: 'BufferReadCmd', ty: 'struct', 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'>Struct <a href='../index.html'>ocl</a>::<wbr><a href='index.html'>builders</a>::<wbr><a class="struct" href=''>BufferReadCmd</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/ocl/standard/buffer.rs.html#657-661' title='goto source code'>[src]</a></span></h1>
<pre class='rust struct'><div class="docblock attributes">#[must_use = "commands do nothing unless enqueued"]
</div>pub struct BufferReadCmd&lt;'c, 'd, T&gt; <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;T: 'c + 'd + <a class="trait" href="../../ocl/traits/trait.OclPrm.html" title="trait ocl::traits::OclPrm">OclPrm</a>,&nbsp;</span> { /* fields omitted */ }</pre><div class='docblock'><p>A buffer command builder used to enqueue reads.</p>
<p>See <a href="https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/clEnqueueReadBuffer.html">SDK</a> docs for more details.</p>
</div>
                    <h2 id='methods' class='small-section-header'>
                      Methods<a href='#methods' class='anchor'></a>
                    </h2>
                <h3 id='impl' class='impl'><span class='in-band'><code>impl&lt;'c, 'd, T&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt; <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;T: <a class="trait" href="../../ocl/traits/trait.OclPrm.html" title="trait ocl::traits::OclPrm">OclPrm</a>,&nbsp;</span></code><a href='#impl' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#663-974' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.queue' class="method"><span id='queue.v' class='invisible'><code>pub fn <a href='#method.queue' class='fnname'>queue</a>(self, queue: &amp;'c <a class="struct" href="../../ocl/struct.Queue.html" title="struct ocl::Queue">Queue</a>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#669-672' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Specifies a queue to use for this call only.</p>
<p>Overrides the buffer's default queue if one is set. If no default
queue is set, this method <strong>must</strong> be called before enqueuing the
command.</p>
</div><h4 id='method.block' class="method"><span id='block.v' class='invisible'><code>pub unsafe fn <a href='#method.block' class='fnname'>block</a>(self, block: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#695-698' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Specifies whether or not to block the current thread until completion.</p>
<p>Ignored if this is not a read or write operation.</p>
<p>Default is <code>block = true</code>.</p>
<h2 id="safety" class="section-header"><a href="#safety">Safety</a></h2>
<p>When performing non-blocking reads or writes, the caller must ensure
that the data being read from or written to is not accessed improperly
until the command completes. Use events (<code>Event::wait_for</code>) or the
command queue (<code>Queue::finish</code>) to synchronize.</p>
<p>If possible, prefer instead to use <a href="builders/struct.BufferMapCmd.html"><code>::map</code></a> with <a href="builders/struct.BufferMapCmd.html"><code>::enq_async</code></a> for
optimal performance and data integrity.</p>
</div><h4 id='method.offset' class="method"><span id='offset.v' class='invisible'><code>pub fn <a href='#method.offset' class='fnname'>offset</a>(self, offset: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#706-708' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Sets the linear offset for an operation.</p>
<h2 id="panics" class="section-header"><a href="#panics">Panics</a></h2>
<p>The 'shape' may not have already been set to rectangular by the
<code>::rect</code> function.</p>
</div><h4 id='method.dst_offset' class="method"><span id='dst_offset.v' class='invisible'><code>pub fn <a href='#method.dst_offset' class='fnname'>dst_offset</a>(self, dst_offset: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#717-724' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Sets an offset into the destination data.</p>
<p>Equivalent to setting the start position of a slice into the
destination data (e.g. <code>dst_data[dst_offset..]</code>). Use <code>::len</code> to set
the end position (resulting in <code>dst_data[dst_offset..len]</code>).</p>
<p>Defaults to 0 if not set. Panics if <code>::rect</code> has been called.</p>
</div><h4 id='method.len' class="method"><span id='len.v' class='invisible'><code>pub fn <a href='#method.len' class='fnname'>len</a>(self, len: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#734-740' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Sets the total length of data to read.</p>
<p>Equivalent to setting the end position of a slice into the destination
data (e.g. <code>destination[..len]</code>). Use <code>::dst_offset</code> to set the start
position (resulting in <code>dst_data[dst_offset..len]</code>).</p>
<p>Defaults to the total length of the read destination provided. Panics
if <code>::rect</code> has been called.</p>
</div><h4 id='method.rect' class="method"><span id='rect.v' class='invisible'><code>pub fn <a href='#method.rect' class='fnname'>rect</a>(<br>&nbsp;&nbsp;&nbsp;&nbsp;self, <br>&nbsp;&nbsp;&nbsp;&nbsp;src_origin: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">; 3]</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;dst_origin: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">; 3]</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;region: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">; 3]</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;src_row_pitch_bytes: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;src_slc_pitch_bytes: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;dst_row_pitch_bytes: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;dst_slc_pitch_bytes: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><br>) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#748-765' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Specifies that this will be a rectangularly shaped operation
(the default being linear).</p>
<p>Row and slice pitches must all be expressed in bytes.</p>
<p>Panics if <code>:offset</code>, <code>dst_offset</code>, or <code>::len</code> have been called.</p>
</div><h4 id='method.ewait' class="method"><span id='ewait.v' class='invisible'><code>pub fn <a href='#method.ewait' class='fnname'>ewait</a>&lt;'e, Ewl&gt;(self, ewait: Ewl) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt; <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;'e: 'c,<br>&nbsp;&nbsp;&nbsp;&nbsp;Ewl: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="enum" href="../../ocl/builders/enum.ClWaitListPtrEnum.html" title="enum ocl::builders::ClWaitListPtrEnum">ClWaitListPtrEnum</a>&lt;'e&gt;&gt;,&nbsp;</span></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#795-799' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Specifies an event or list of events to wait on before the command
will run.</p>
<p>When events generated using the <code>::enew</code> method of <strong>other</strong>,
previously enqueued commands are passed here (either individually or
as part of an <a href="struct.EventList.html"><code>EventList</code></a>), this command will not execute until
those commands have completed.</p>
<p>Using events can compliment the use of queues to order commands by
creating temporal dependencies between them (where commands in one
queue must wait for the completion of commands in another). Events can
also supplant queues altogether when, for example, using out-of-order
queues.</p>
<h1 id="example" class="section-header"><a href="#example">Example</a></h1>
<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="comment">// Create an event list:</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">event_list</span> <span class="op">=</span> <span class="ident">EventList</span>::<span class="ident">new</span>();
<span class="comment">// Enqueue a kernel on `queue_1`, creating an event representing the kernel</span>
<span class="comment">// command in our list:</span>
<span class="ident">kernel</span>.<span class="ident">cmd</span>().<span class="ident">queue</span>(<span class="kw-2">&amp;</span><span class="ident">queue_1</span>).<span class="ident">enew</span>(<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">event_list</span>).<span class="ident">enq</span>()<span class="question-mark">?</span>;
<span class="comment">// Read from a buffer using `queue_2`, ensuring the read does not begin until</span>
<span class="comment">// after the kernel command has completed:</span>
<span class="ident">buffer</span>.<span class="ident">read</span>(<span class="ident">rwvec</span>.<span class="ident">clone</span>()).<span class="ident">queue</span>(<span class="kw-2">&amp;</span><span class="ident">queue_2</span>).<span class="ident">ewait</span>(<span class="kw-2">&amp;</span><span class="ident">event_list</span>).<span class="ident">enq_async</span>()<span class="question-mark">?</span>;</pre>
</div><h4 id='method.enew' class="method"><span id='enew.v' class='invisible'><code>pub fn <a href='#method.enew' class='fnname'>enew</a>&lt;'e, En&gt;(self, enew: En) -&gt; <a class="struct" href="../../ocl/builders/struct.BufferReadCmd.html" title="struct ocl::builders::BufferReadCmd">BufferReadCmd</a>&lt;'c, 'd, T&gt; <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;'e: 'c,<br>&nbsp;&nbsp;&nbsp;&nbsp;En: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="enum" href="../../ocl/builders/enum.ClNullEventPtrEnum.html" title="enum ocl::builders::ClNullEventPtrEnum">ClNullEventPtrEnum</a>&lt;'e&gt;&gt;,&nbsp;</span></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#832-836' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Specifies the destination to store a new, optionally created event
associated with this command.</p>
<p>The destination can be a mutable reference to an empty event (created
using <a href="struct.Event.html#method.empty"><code>Event::empty</code></a>) or a mutable reference to an event list.</p>
<p>After this command is enqueued, the event in the destination can be
passed to the <code>::ewait</code> method of another command. Doing so will cause
the other command to wait until this command has completed before
executing.</p>
<p>Using events can compliment the use of queues to order commands by
creating temporal dependencies between them (where commands in one
queue must wait for the completion of commands in another). Events can
also supplant queues altogether when, for example, using out-of-order
queues.</p>
<h1 id="example-1" class="section-header"><a href="#example-1">Example</a></h1>
<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="comment">// Create an event list:</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">event</span> <span class="op">=</span> <span class="ident">Event</span>::<span class="ident">empty</span>();
<span class="comment">// Enqueue a kernel on `queue_1`, creating an event representing the kernel</span>
<span class="comment">// command in our list:</span>
<span class="ident">kernel</span>.<span class="ident">cmd</span>().<span class="ident">queue</span>(<span class="kw-2">&amp;</span><span class="ident">queue_1</span>).<span class="ident">enew</span>(<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">event</span>).<span class="ident">enq</span>()<span class="question-mark">?</span>;
<span class="comment">// Read from a buffer using `queue_2`, ensuring the read does not begin until</span>
<span class="comment">// after the kernel command has completed:</span>
<span class="ident">buffer</span>.<span class="ident">read</span>(<span class="ident">rwvec</span>.<span class="ident">clone</span>()).<span class="ident">queue</span>(<span class="kw-2">&amp;</span><span class="ident">queue_2</span>).<span class="ident">ewait</span>(<span class="kw-2">&amp;</span><span class="ident">event</span>).<span class="ident">enq_async</span>()<span class="question-mark">?</span>;</pre>
</div><h4 id='method.enq' class="method"><span id='enq.v' class='invisible'><code>pub fn <a href='#method.enq' class='fnname'>enq</a>(self) -&gt; <a class="type" href="../../ocl/error/type.Result.html" title="type ocl::error::Result">OclResult</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#845-902' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Enqueues this command, blocking the current thread until it is complete.</p>
<p>If an <code>RwVec</code> is being used as the data destination, the current
thread will be blocked until an exclusive lock can be obtained before
running the command (which will also block for its duration).</p>
</div><h4 id='method.enq_async' class="method"><span id='enq_async.v' class='invisible'><code>pub fn <a href='#method.enq_async' class='fnname'>enq_async</a>(self) -&gt; <a class="type" href="../../ocl/error/type.Result.html" title="type ocl::error::Result">OclResult</a>&lt;<a class="type" href="../../ocl/async/type.FutureWriteGuard.html" title="type ocl::async::FutureWriteGuard">FutureWriteGuard</a>&lt;<a class="struct" href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;T&gt;&gt;&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/ocl/standard/buffer.rs.html#911-973' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Enqueues this command and returns a future representing its completion
which resolves to a guard providing exclusive data access usable
within subsequent futures.</p>
<p>A data destination container appropriate for an asynchronous operation
(such as <code>RwVec</code>) must have been passed to <code>::read</code>.</p>
</div></div></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 = "ocl";
    </script>
    <script src="../../main.js"></script>
    <script defer src="../../search-index.js"></script>
</body>
</html>