230 lines
No EOL
17 KiB
HTML
230 lines
No EOL
17 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="API documentation for the Rust `Condvar` struct in crate `bitflags`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, Condvar">
|
||
|
||
<title>bitflags::__core::sync::Condvar - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../../../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../../../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'><a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a href='index.html'>sync</a></p><script>window.sidebarCurrent = {name: 'Condvar', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script>
|
||
</nav>
|
||
|
||
<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 struct">
|
||
<h1 class='fqn'><span class='in-band'>Struct <a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a href='index.html'>sync</a>::<wbr><a class='struct' href=''>Condvar</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'>−</span>]
|
||
</a>
|
||
</span><a id='src-9984' class='srclink' href='https://doc.rust-lang.org/nightly/std/sync/condvar/struct.Condvar.html?gotosrc=9984' title='goto source code'>[src]</a></span></h1>
|
||
<pre class='rust struct'>pub struct Condvar {
|
||
// some fields omitted
|
||
}</pre><span class="since">1.0.0</span><div class='docblock'><p>A Condition Variable</p>
|
||
|
||
<p>Condition variables represent the ability to block a thread such that it
|
||
consumes no CPU time while waiting for an event to occur. Condition
|
||
variables are typically associated with a boolean predicate (a condition)
|
||
and a mutex. The predicate is always verified inside of the mutex before
|
||
determining that thread must block.</p>
|
||
|
||
<p>Functions in this module will block the current <strong>thread</strong> of execution and
|
||
are bindings to system-provided condition variables where possible. Note
|
||
that this module places one additional restriction over the system condition
|
||
variables: each condvar can be used with precisely one mutex at runtime. Any
|
||
attempt to use multiple mutexes on the same condition variable will result
|
||
in a runtime panic. If this is not desired, then the unsafe primitives in
|
||
<code>sys</code> do not have this restriction but may result in undefined behavior.</p>
|
||
|
||
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>sync</span>::{<span class='ident'>Arc</span>, <span class='ident'>Mutex</span>, <span class='ident'>Condvar</span>};
|
||
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>thread</span>;
|
||
|
||
<span class='kw'>let</span> <span class='ident'>pair</span> <span class='op'>=</span> <span class='ident'>Arc</span>::<span class='ident'>new</span>((<span class='ident'>Mutex</span>::<span class='ident'>new</span>(<span class='boolval'>false</span>), <span class='ident'>Condvar</span>::<span class='ident'>new</span>()));
|
||
<span class='kw'>let</span> <span class='ident'>pair2</span> <span class='op'>=</span> <span class='ident'>pair</span>.<span class='ident'>clone</span>();
|
||
|
||
<span class='comment'>// Inside of our lock, spawn a new thread, and then wait for it to start</span>
|
||
<span class='ident'>thread</span>::<span class='ident'>spawn</span>(<span class='kw'>move</span><span class='op'>||</span> {
|
||
<span class='kw'>let</span> <span class='kw-2'>&</span>(<span class='kw-2'>ref</span> <span class='ident'>lock</span>, <span class='kw-2'>ref</span> <span class='ident'>cvar</span>) <span class='op'>=</span> <span class='kw-2'>&</span><span class='op'>*</span><span class='ident'>pair2</span>;
|
||
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>started</span> <span class='op'>=</span> <span class='ident'>lock</span>.<span class='ident'>lock</span>().<span class='ident'>unwrap</span>();
|
||
<span class='op'>*</span><span class='ident'>started</span> <span class='op'>=</span> <span class='boolval'>true</span>;
|
||
<span class='ident'>cvar</span>.<span class='ident'>notify_one</span>();
|
||
});
|
||
|
||
<span class='comment'>// wait for the thread to start up</span>
|
||
<span class='kw'>let</span> <span class='kw-2'>&</span>(<span class='kw-2'>ref</span> <span class='ident'>lock</span>, <span class='kw-2'>ref</span> <span class='ident'>cvar</span>) <span class='op'>=</span> <span class='kw-2'>&</span><span class='op'>*</span><span class='ident'>pair</span>;
|
||
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>started</span> <span class='op'>=</span> <span class='ident'>lock</span>.<span class='ident'>lock</span>().<span class='ident'>unwrap</span>();
|
||
<span class='kw'>while</span> <span class='op'>!</span><span class='op'>*</span><span class='ident'>started</span> {
|
||
<span class='ident'>started</span> <span class='op'>=</span> <span class='ident'>cvar</span>.<span class='ident'>wait</span>(<span class='ident'>started</span>).<span class='ident'>unwrap</span>();
|
||
}</pre>
|
||
</div><h2 id='methods'>Methods</h2><h3 class='impl'><code>impl <a class='struct' href='../../../bitflags/__core/sync/struct.Condvar.html' title='bitflags::__core::sync::Condvar'>Condvar</a></code></h3><div class='impl-items'><h4 id='method.new' class='method'><code>fn <a href='#method.new' class='fnname'>new</a>() -> <a class='struct' href='../../../bitflags/__core/sync/struct.Condvar.html' title='bitflags::__core::sync::Condvar'>Condvar</a></code></h4>
|
||
<div class='docblock'><p>Creates a new condition variable which is ready to be waited on and
|
||
notified.</p>
|
||
</div><h4 id='method.wait' class='method'><code>fn <a href='#method.wait' class='fnname'>wait</a><T>(&self, guard: <a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>) -> <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a><<a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, <a class='struct' href='../../../bitflags/__core/sync/struct.PoisonError.html' title='bitflags::__core::sync::PoisonError'>PoisonError</a><<a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>>></code></h4>
|
||
<div class='docblock'><p>Blocks the current thread until this condition variable receives a
|
||
notification.</p>
|
||
|
||
<p>This function will atomically unlock the mutex specified (represented by
|
||
<code>mutex_guard</code>) and block the current thread. This means that any calls
|
||
to <code>notify_*()</code> which happen logically after the mutex is unlocked are
|
||
candidates to wake this thread up. When this function call returns, the
|
||
lock specified will have been re-acquired.</p>
|
||
|
||
<p>Note that this function is susceptible to spurious wakeups. Condition
|
||
variables normally have a boolean predicate associated with them, and
|
||
the predicate must always be checked each time this function returns to
|
||
protect against spurious wakeups.</p>
|
||
|
||
<h1 id='errors' class='section-header'><a href='#errors'>Errors</a></h1>
|
||
<p>This function will return an error if the mutex being waited on is
|
||
poisoned when this thread re-acquires the lock. For more information,
|
||
see information about poisoning on the Mutex type.</p>
|
||
|
||
<h1 id='panics' class='section-header'><a href='#panics'>Panics</a></h1>
|
||
<p>This function will <code>panic!()</code> if it is used with more than one mutex
|
||
over time. Each condition variable is dynamically bound to exactly one
|
||
mutex to ensure defined behavior across platforms. If this functionality
|
||
is not desired, then unsafe primitives in <code>sys</code> are provided.</p>
|
||
</div><h4 id='method.wait_timeout_ms' class='method'><code>fn <a href='#method.wait_timeout_ms' class='fnname'>wait_timeout_ms</a><T>(&self, guard: <a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, ms: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u32.html'>u32</a>) -> <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>(</a><a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.bool.html'>bool</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>)</a>, <a class='struct' href='../../../bitflags/__core/sync/struct.PoisonError.html' title='bitflags::__core::sync::PoisonError'>PoisonError</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>(</a><a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.bool.html'>bool</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>)</a>>></code></h4>
|
||
<div class='stability'><em class='stab deprecated'>Deprecated since 1.6.0<p>: replaced by <code>std::sync::Condvar::wait_timeout</code></p>
|
||
</em></div><div class='docblock'><p>Waits on this condition variable for a notification, timing out after a
|
||
specified duration.</p>
|
||
|
||
<p>The semantics of this function are equivalent to <code>wait()</code>
|
||
except that the thread will be blocked for roughly no longer
|
||
than <code>ms</code> milliseconds. This method should not be used for
|
||
precise timing due to anomalies such as preemption or platform
|
||
differences that may not cause the maximum amount of time
|
||
waited to be precisely <code>ms</code>.</p>
|
||
|
||
<p>The returned boolean is <code>false</code> only if the timeout is known
|
||
to have elapsed.</p>
|
||
|
||
<p>Like <code>wait</code>, the lock specified will be re-acquired when this function
|
||
returns, regardless of whether the timeout elapsed or not.</p>
|
||
</div><h4 id='method.wait_timeout' class='method'><code>fn <a href='#method.wait_timeout' class='fnname'>wait_timeout</a><T>(&self, guard: <a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, dur: <a class='struct' href='../../../bitflags/__core/time/struct.Duration.html' title='bitflags::__core::time::Duration'>Duration</a>) -> <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>(</a><a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, <a class='struct' href='../../../bitflags/__core/sync/struct.WaitTimeoutResult.html' title='bitflags::__core::sync::WaitTimeoutResult'>WaitTimeoutResult</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>)</a>, <a class='struct' href='../../../bitflags/__core/sync/struct.PoisonError.html' title='bitflags::__core::sync::PoisonError'>PoisonError</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>(</a><a class='struct' href='../../../bitflags/__core/sync/struct.MutexGuard.html' title='bitflags::__core::sync::MutexGuard'>MutexGuard</a><'a, T>, <a class='struct' href='../../../bitflags/__core/sync/struct.WaitTimeoutResult.html' title='bitflags::__core::sync::WaitTimeoutResult'>WaitTimeoutResult</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>)</a>>></code><span class="since">1.5.0</span></h4>
|
||
<div class='docblock'><p>Waits on this condition variable for a notification, timing out after a
|
||
specified duration.</p>
|
||
|
||
<p>The semantics of this function are equivalent to <code>wait()</code> except that
|
||
the thread will be blocked for roughly no longer than <code>dur</code>. This
|
||
method should not be used for precise timing due to anomalies such as
|
||
preemption or platform differences that may not cause the maximum
|
||
amount of time waited to be precisely <code>dur</code>.</p>
|
||
|
||
<p>The returned <code>WaitTimeoutResult</code> value indicates if the timeout is
|
||
known to have elapsed.</p>
|
||
|
||
<p>Like <code>wait</code>, the lock specified will be re-acquired when this function
|
||
returns, regardless of whether the timeout elapsed or not.</p>
|
||
</div><h4 id='method.notify_one' class='method'><code>fn <a href='#method.notify_one' class='fnname'>notify_one</a>(&self)</code></h4>
|
||
<div class='docblock'><p>Wakes up one blocked thread on this condvar.</p>
|
||
|
||
<p>If there is a blocked thread on this condition variable, then it will
|
||
be woken up from its call to <code>wait</code> or <code>wait_timeout</code>. Calls to
|
||
<code>notify_one</code> are not buffered in any way.</p>
|
||
|
||
<p>To wake up all threads, see <code>notify_all()</code>.</p>
|
||
</div><h4 id='method.notify_all' class='method'><code>fn <a href='#method.notify_all' class='fnname'>notify_all</a>(&self)</code></h4>
|
||
<div class='docblock'><p>Wakes up all blocked threads on this condvar.</p>
|
||
|
||
<p>This method will ensure that any current waiters on the condition
|
||
variable are awoken. Calls to <code>notify_all()</code> are not buffered in any
|
||
way.</p>
|
||
|
||
<p>To wake up only one thread, see <code>notify_one()</code>.</p>
|
||
</div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><code>impl <a class='trait' href='../../../bitflags/__core/default/trait.Default.html' title='bitflags::__core::default::Default'>Default</a> for <a class='struct' href='../../../bitflags/__core/sync/struct.Condvar.html' title='bitflags::__core::sync::Condvar'>Condvar</a></code><span class="since">1.9.0</span></h3><div class='impl-items'><h4 id='method.default' class='method'><code>fn <a href='../../../bitflags/__core/default/trait.Default.html#tymethod.default' class='fnname'>default</a>() -> <a class='struct' href='../../../bitflags/__core/sync/struct.Condvar.html' title='bitflags::__core::sync::Condvar'>Condvar</a></code></h4>
|
||
</div><h3 class='impl'><code>impl <a class='trait' href='../../../bitflags/__core/ops/trait.Drop.html' title='bitflags::__core::ops::Drop'>Drop</a> for <a class='struct' href='../../../bitflags/__core/sync/struct.Condvar.html' title='bitflags::__core::sync::Condvar'>Condvar</a></code></h3><div class='impl-items'><h4 id='method.drop' class='method'><code>fn <a href='../../../bitflags/__core/ops/trait.Drop.html#tymethod.drop' class='fnname'>drop</a>(&mut self)</code></h4>
|
||
</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>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</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 = "bitflags";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../../../jquery.js"></script>
|
||
<script src="../../../main.js"></script>
|
||
|
||
<script defer src="../../../search-index.js"></script>
|
||
</body>
|
||
</html> |