cassandra-server
Version:
A thin Javascript wrapper around Apache Cassandra to provide out of the box server support
440 lines (438 loc) • 19.7 kB
HTML
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (version 1.7.0_67) on Sun Sep 07 15:29:30 CEST 2014 -->
<title>WaitQueue (apache-cassandra API)</title>
<meta name="date" content="2014-09-07">
<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style">
</head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="WaitQueue (apache-cassandra API)";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/WaitQueue.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../org/apache/cassandra/utils/concurrent/SimpleCondition.html" title="class in org.apache.cassandra.utils.concurrent"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.AbstractSignal.html" title="class in org.apache.cassandra.utils.concurrent"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../index.html?org/apache/cassandra/utils/concurrent/WaitQueue.html" target="_top">Frames</a></li>
<li><a href="WaitQueue.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary: </li>
<li><a href="#nested_class_summary">Nested</a> | </li>
<li>Field | </li>
<li><a href="#constructor_summary">Constr</a> | </li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail: </li>
<li>Field | </li>
<li><a href="#constructor_detail">Constr</a> | </li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.cassandra.utils.concurrent</div>
<h2 title="Class WaitQueue" class="title">Class WaitQueue</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li>java.lang.Object</li>
<li>
<ul class="inheritance">
<li>org.apache.cassandra.utils.concurrent.WaitQueue</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>public final class <span class="strong">WaitQueue</span>
extends java.lang.Object</pre>
<div class="block"><p>A relatively easy to use utility for general purpose thread signalling.</p>
<p>Usage on a thread awaiting a state change using a WaitQueue q is:</p>
<pre>
<code>while (!conditionMet())
Signal s = q.register();
if (!conditionMet()) // or, perhaps more correctly, !conditionChanged()
s.await();
else
s.cancel();
</code>
</pre>
A signalling thread, AFTER changing the state, then calls q.signal() to wake up one, or q.signalAll()
to wake up all, waiting threads.
<p>To understand intuitively how this class works, the idea is simply that a thread, once it considers itself
incapable of making progress, registers to be awoken once that changes. Since this could have changed between
checking and registering (in which case the thread that made this change would have been unable to signal it),
it checks the condition again, sleeping only if it hasn't changed/still is not met.</p>
<p>This thread synchronisation scheme has some advantages over Condition objects and Object.wait/notify in that no monitor
acquisition is necessary and, in fact, besides the actual waiting on a signal, all operations are non-blocking.
As a result consumers can never block producers, nor each other, or vice versa, from making progress.
Threads that are signalled are also put into a RUNNABLE state almost simultaneously, so they can all immediately make
progress without having to serially acquire the monitor/lock, reducing scheduler delay incurred.</p>
<p>A few notes on utilisation:</p>
<p>1. A thread will only exit await() when it has been signalled, but this does not guarantee the condition has not
been altered since it was signalled, and depending on your design it is likely the outer condition will need to be
checked in a loop, though this is not always the case.</p>
<p>2. Each signal is single use, so must be re-registered after each await(). This is true even if it times out.</p>
<p>3. If you choose not to wait on the signal (because the condition has been met before you waited on it)
you must cancel() the signal if the signalling thread uses signal() to awake waiters; otherwise signals will be
lost. If signalAll() is used but infrequent, and register() is frequent, cancel() should still be used to prevent the
queue growing unboundedly. Similarly, if you provide a TimerContext, cancel should be used to ensure it is not erroneously
counted towards wait time.</p>
<p>4. Care must be taken when selecting conditionMet() to ensure we are waiting on the condition that actually
indicates progress is possible. In some complex cases it may be tempting to wait on a condition that is only indicative
of local progress, not progress on the task we are aiming to complete, and a race may leave us waiting for a condition
to be met that we no longer need.
<p>5. This scheme is not fair</p>
<p>6. Only the thread that calls register() may call await()</p></div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ======== NESTED CLASS SUMMARY ======== -->
<ul class="blockList">
<li class="blockList"><a name="nested_class_summary">
<!-- -->
</a>
<h3>Nested Class Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Nested Class Summary table, listing nested classes, and an explanation">
<caption><span>Nested Classes</span><span class="tabEnd"> </span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Class and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static class </code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.AbstractSignal.html" title="class in org.apache.cassandra.utils.concurrent">WaitQueue.AbstractSignal</a></strong></code>
<div class="block">An abstract signal implementation</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>static interface </code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a></strong></code>
<div class="block">A Signal is a one-time-use mechanism for a thread to wait for notification that some condition
state has transitioned that it may be interested in (and hence should check if it is).</div>
</td>
</tr>
</table>
</li>
</ul>
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor_summary">
<!-- -->
</a>
<h3>Constructor Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Constructor Summary table, listing constructors, and an explanation">
<caption><span>Constructors</span><span class="tabEnd"> </span></caption>
<tr>
<th class="colOne" scope="col">Constructor and Description</th>
</tr>
<tr class="altColor">
<td class="colOne"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#WaitQueue()">WaitQueue</a></strong>()</code> </td>
</tr>
</table>
</li>
</ul>
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method_summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span>Methods</span><span class="tabEnd"> </span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a></code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#all(org.apache.cassandra.utils.concurrent.WaitQueue.Signal...)">all</a></strong>(<a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a>... signals)</code> </td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>static <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a></code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#any(org.apache.cassandra.utils.concurrent.WaitQueue.Signal...)">any</a></strong>(<a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a>... signals)</code> </td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>int</code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#getWaiting()">getWaiting</a></strong>()</code>
<div class="block">Return how many threads are waiting</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#hasWaiters()">hasWaiters</a></strong>()</code> </td>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a></code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#register()">register</a></strong>()</code>
<div class="block">The calling thread MUST be the thread that uses the signal</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a></code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#register(com.yammer.metrics.core.TimerContext)">register</a></strong>(com.yammer.metrics.core.TimerContext context)</code>
<div class="block">The calling thread MUST be the thread that uses the signal.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#signal()">signal</a></strong>()</code>
<div class="block">Signal one waiting thread</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><code><strong><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.html#signalAll()">signalAll</a></strong>()</code>
<div class="block">Signal all waiting threads</div>
</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a name="methods_inherited_from_class_java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class java.lang.Object</h3>
<code>clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</code></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor_detail">
<!-- -->
</a>
<h3>Constructor Detail</h3>
<a name="WaitQueue()">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>WaitQueue</h4>
<pre>public WaitQueue()</pre>
</li>
</ul>
</li>
</ul>
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method_detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="register()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>register</h4>
<pre>public <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a> register()</pre>
<div class="block">The calling thread MUST be the thread that uses the signal</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>x</dd></dl>
</li>
</ul>
<a name="register(com.yammer.metrics.core.TimerContext)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>register</h4>
<pre>public <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a> register(com.yammer.metrics.core.TimerContext context)</pre>
<div class="block">The calling thread MUST be the thread that uses the signal.
If the Signal is waited on, context.stop() will be called when the wait times out, the Signal is signalled,
or the waiting thread is interrupted.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd></dd></dl>
</li>
</ul>
<a name="signal()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>signal</h4>
<pre>public boolean signal()</pre>
<div class="block">Signal one waiting thread</div>
</li>
</ul>
<a name="signalAll()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>signalAll</h4>
<pre>public void signalAll()</pre>
<div class="block">Signal all waiting threads</div>
</li>
</ul>
<a name="hasWaiters()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>hasWaiters</h4>
<pre>public boolean hasWaiters()</pre>
</li>
</ul>
<a name="getWaiting()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>getWaiting</h4>
<pre>public int getWaiting()</pre>
<div class="block">Return how many threads are waiting</div>
<dl><dt><span class="strong">Returns:</span></dt><dd></dd></dl>
</li>
</ul>
<a name="any(org.apache.cassandra.utils.concurrent.WaitQueue.Signal...)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>any</h4>
<pre>public static <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a> any(<a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a>... signals)</pre>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>signals</code> - </dd>
<dt><span class="strong">Returns:</span></dt><dd>a signal that returns only when any of the provided signals would have returned</dd></dl>
</li>
</ul>
<a name="all(org.apache.cassandra.utils.concurrent.WaitQueue.Signal...)">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>all</h4>
<pre>public static <a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a> all(<a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.Signal.html" title="interface in org.apache.cassandra.utils.concurrent">WaitQueue.Signal</a>... signals)</pre>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>signals</code> - </dd>
<dt><span class="strong">Returns:</span></dt><dd>a signal that returns only when all provided signals would have returned</dd></dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/WaitQueue.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../org/apache/cassandra/utils/concurrent/SimpleCondition.html" title="class in org.apache.cassandra.utils.concurrent"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../../org/apache/cassandra/utils/concurrent/WaitQueue.AbstractSignal.html" title="class in org.apache.cassandra.utils.concurrent"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../index.html?org/apache/cassandra/utils/concurrent/WaitQueue.html" target="_top">Frames</a></li>
<li><a href="WaitQueue.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary: </li>
<li><a href="#nested_class_summary">Nested</a> | </li>
<li>Field | </li>
<li><a href="#constructor_summary">Constr</a> | </li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail: </li>
<li>Field | </li>
<li><a href="#constructor_detail">Constr</a> | </li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small>Copyright © 2014 The Apache Software Foundation</small></p>
</body>
</html>