59 lines
15 KiB
HTML
59 lines
15 KiB
HTML
<!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="A `Producer` is effectively a “splittable `IntoIterator`”. That is, a producer is a value which can be converted into an iterator at any time: at that point, it simply produces items on demand, like any iterator. But what makes a `Producer` special is that, before we convert to an iterator, we can also split it at a particular point using the `split_at` method. This will yield up two producers, one producing the items before that point, and one producing the items after that point (these two producers can then independently be split further, or be converted into iterators). In Rayon, this splitting is used to divide between threads. See the `plumbing` README for further details."><title>Producer in rayon::iter::plumbing - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="rayon" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Producer</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../rayon/index.html">rayon</a><span class="version">1.11.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Producer</a></h2><h3><a href="#required-associated-types">Required Associated Types</a></h3><ul class="block"><li><a href="#associatedtype.IntoIter" title="IntoIter">IntoIter</a></li><li><a href="#associatedtype.Item" title="Item">Item</a></li></ul><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.into_iter" title="into_iter">into_iter</a></li><li><a href="#tymethod.split_at" title="split_at">split_at</a></li></ul><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.fold_with" title="fold_with">fold_with</a></li><li><a href="#method.max_len" title="max_len">max_len</a></li><li><a href="#method.min_len" title="min_len">min_len</a></li></ul><h3><a href="#dyn-compatibility">Dyn Compatibility</a></h3><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In rayon::<wbr>iter::<wbr>plumbing</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">rayon</a>::<wbr><a href="../index.html">iter</a>::<wbr><a href="index.html">plumbing</a></div><h1>Trait <span class="trait">Producer</span> <button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/rayon/iter/plumbing/mod.rs.html#56-109">Source</a> </span></div><pre class="rust item-decl"><code>pub trait Producer: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> {
|
|
type <a href="#associatedtype.Item" class="associatedtype">Item</a>;
|
|
type <a href="#associatedtype.IntoIter" class="associatedtype">IntoIter</a>: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator">Iterator</a><Item = Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.Item" title="type rayon::iter::plumbing::Producer::Item">Item</a>> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/double_ended/trait.DoubleEndedIterator.html" title="trait core::iter::traits::double_ended::DoubleEndedIterator">DoubleEndedIterator</a> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/exact_size/trait.ExactSizeIterator.html" title="trait core::iter::traits::exact_size::ExactSizeIterator">ExactSizeIterator</a>;
|
|
|
|
// Required methods
|
|
fn <a href="#tymethod.into_iter" class="fn">into_iter</a>(self) -> Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.IntoIter" title="type rayon::iter::plumbing::Producer::IntoIter">IntoIter</a>;
|
|
<span class="item-spacer"></span> fn <a href="#tymethod.split_at" class="fn">split_at</a>(self, index: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a>) -> (Self, Self);
|
|
|
|
// Provided methods
|
|
fn <a href="#method.min_len" class="fn">min_len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a> { ... }
|
|
<span class="item-spacer"></span> fn <a href="#method.max_len" class="fn">max_len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a> { ... }
|
|
<span class="item-spacer"></span> fn <a href="#method.fold_with" class="fn">fold_with</a><F>(self, folder: F) -> F
|
|
<span class="where">where F: <a class="trait" href="trait.Folder.html" title="trait rayon::iter::plumbing::Folder">Folder</a><Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.Item" title="type rayon::iter::plumbing::Producer::Item">Item</a>></span> { ... }
|
|
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A <code>Producer</code> is effectively a “splittable <code>IntoIterator</code>”. That
|
|
is, a producer is a value which can be converted into an iterator
|
|
at any time: at that point, it simply produces items on demand,
|
|
like any iterator. But what makes a <code>Producer</code> special is that,
|
|
<em>before</em> we convert to an iterator, we can also <strong>split</strong> it at a
|
|
particular point using the <code>split_at</code> method. This will yield up
|
|
two producers, one producing the items before that point, and one
|
|
producing the items after that point (these two producers can then
|
|
independently be split further, or be converted into iterators).
|
|
In Rayon, this splitting is used to divide between threads.
|
|
See <a href="https://github.com/rayon-rs/rayon/blob/main/src/iter/plumbing/README.md">the <code>plumbing</code> README</a> for further details.</p>
|
|
<p>Note that each producer will always produce a fixed number of
|
|
items N. However, this number N is not queryable through the API;
|
|
the consumer is expected to track it.</p>
|
|
<p>NB. You might expect <code>Producer</code> to extend the <code>IntoIterator</code>
|
|
trait. However, <a href="https://github.com/rust-lang/rust/issues/20671">rust-lang/rust#20671</a> prevents us from
|
|
declaring the DoubleEndedIterator and ExactSizeIterator
|
|
constraints on a required IntoIterator trait, so we inline
|
|
IntoIterator here until that issue is fixed.</p>
|
|
</div></details><h2 id="required-associated-types" class="section-header">Required Associated Types<a href="#required-associated-types" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedtype.Item" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#59">Source</a><h4 class="code-header">type <a href="#associatedtype.Item" class="associatedtype">Item</a></h4></section></summary><div class="docblock"><p>The type of item that will be produced by this producer once
|
|
it is converted into an iterator.</p>
|
|
</div></details><details class="toggle" open><summary><section id="associatedtype.IntoIter" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#62">Source</a><h4 class="code-header">type <a href="#associatedtype.IntoIter" class="associatedtype">IntoIter</a>: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator">Iterator</a><Item = Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.Item" title="type rayon::iter::plumbing::Producer::Item">Item</a>> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/double_ended/trait.DoubleEndedIterator.html" title="trait core::iter::traits::double_ended::DoubleEndedIterator">DoubleEndedIterator</a> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/iter/traits/exact_size/trait.ExactSizeIterator.html" title="trait core::iter::traits::exact_size::ExactSizeIterator">ExactSizeIterator</a></h4></section></summary><div class="docblock"><p>The type of iterator we will become.</p>
|
|
</div></details></div><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.into_iter" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#66">Source</a><h4 class="code-header">fn <a href="#tymethod.into_iter" class="fn">into_iter</a>(self) -> Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.IntoIter" title="type rayon::iter::plumbing::Producer::IntoIter">IntoIter</a></h4></section></summary><div class="docblock"><p>Convert <code>self</code> into an iterator; at this point, no more parallel splits
|
|
are possible.</p>
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.split_at" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#97">Source</a><h4 class="code-header">fn <a href="#tymethod.split_at" class="fn">split_at</a>(self, index: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a>) -> (Self, Self)</h4></section></summary><div class="docblock"><p>Split into two producers; one produces items <code>0..index</code>, the
|
|
other <code>index..N</code>. Index must be less than or equal to <code>N</code>.</p>
|
|
</div></details></div><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.min_len" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#78-80">Source</a><h4 class="code-header">fn <a href="#method.min_len" class="fn">min_len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>The minimum number of items that we will process
|
|
sequentially. Defaults to 1, which means that we will split
|
|
all the way down to a single item. This can be raised higher
|
|
using the <a href="../trait.IndexedParallelIterator.html#method.with_min_len" title="method rayon::iter::IndexedParallelIterator::with_min_len"><code>with_min_len</code></a> method, which will force us to
|
|
create sequential tasks at a larger granularity. Note that
|
|
Rayon automatically normally attempts to adjust the size of
|
|
parallel splits to reduce overhead, so this should not be
|
|
needed.</p>
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.max_len" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#91-93">Source</a><h4 class="code-header">fn <a href="#method.max_len" class="fn">max_len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>The maximum number of items that we will process
|
|
sequentially. Defaults to MAX, which means that we can choose
|
|
not to split at all. This can be lowered using the
|
|
<a href="../trait.IndexedParallelIterator.html#method.with_max_len" title="method rayon::iter::IndexedParallelIterator::with_max_len"><code>with_max_len</code></a> method, which will force us to create more
|
|
parallel tasks. Note that Rayon automatically normally
|
|
attempts to adjust the size of parallel splits to reduce
|
|
overhead, so this should not be needed.</p>
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.fold_with" class="method"><a class="src rightside" href="../../../src/rayon/iter/plumbing/mod.rs.html#103-108">Source</a><h4 class="code-header">fn <a href="#method.fold_with" class="fn">fold_with</a><F>(self, folder: F) -> F<div class="where">where
|
|
F: <a class="trait" href="trait.Folder.html" title="trait rayon::iter::plumbing::Folder">Folder</a><Self::<a class="associatedtype" href="trait.Producer.html#associatedtype.Item" title="type rayon::iter::plumbing::Producer::Item">Item</a>>,</div></h4></section></summary><div class="docblock"><p>Iterate the producer, feeding each element to <code>folder</code>, and
|
|
stop when the folder is full (or all elements have been consumed).</p>
|
|
<p>The provided implementation is sufficient for most iterables.</p>
|
|
</div></details></div><h2 id="dyn-compatibility" class="section-header">Dyn Compatibility<a href="#dyn-compatibility" class="anchor">§</a></h2><div class="dyn-compatibility-info"><p>This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.93.1/reference/items/traits.html#dyn-compatibility">dyn compatible</a>.</p><p><i>In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.</i></p></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"></div><script src="../../../trait.impl/rayon/iter/plumbing/trait.Producer.js" async></script></section></div></main></body></html> |