parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="Queues" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/asyncio-queue.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/asyncio/queues.py asyncio queues are designed to be similar to classes of the queue module. Although asyncio queues are not thread-safe, they are designed to be used specifically i..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_asyncio-queue_26850ff4.png" />15<meta property="og:image:alt" content="Source code: Lib/asyncio/queues.py asyncio queues are designed to be similar to classes of the queue module. Although asyncio queues are not thread-safe, they are designed to be used specifically i..." />16<meta name="description" content="Source code: Lib/asyncio/queues.py asyncio queues are designed to be similar to classes of the queue module. Although asyncio queues are not thread-safe, they are designed to be used specifically i..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>Queues — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="Exceptions" href="asyncio-exceptions.html" />43 <link rel="prev" title="Subprocesses" href="asyncio-subprocess.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/asyncio-queue.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#">Queues</a><ul>108<li><a class="reference internal" href="#queue">Queue</a></li>109<li><a class="reference internal" href="#priority-queue">Priority Queue</a></li>110<li><a class="reference internal" href="#lifo-queue">LIFO Queue</a></li>111<li><a class="reference internal" href="#exceptions">Exceptions</a></li>112<li><a class="reference internal" href="#examples">Examples</a></li>113</ul>114</li>115</ul>116 117 </div>118 <div>119 <h4>Previous topic</h4>120 <p class="topless"><a href="asyncio-subprocess.html"121 title="previous chapter">Subprocesses</a></p>122 </div>123 <div>124 <h4>Next topic</h4>125 <p class="topless"><a href="asyncio-exceptions.html"126 title="next chapter">Exceptions</a></p>127 </div>128 <script>129 document.addEventListener('DOMContentLoaded', () => {130 const title = document.querySelector('meta[property="og:title"]').content;131 const elements = document.querySelectorAll('.improvepage');132 const pageurl = window.location.href.split('?')[0];133 elements.forEach(element => {134 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));135 url.searchParams.set('pagetitle', title);136 url.searchParams.set('pageurl', pageurl);137 url.searchParams.set('pagesource', "library/asyncio-queue.rst");138 element.href = url.toString();139 });140 });141 </script>142 <div role="note" aria-label="source link">143 <h3>This page</h3>144 <ul class="this-page-menu">145 <li><a href="../bugs.html">Report a bug</a></li>146 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>147 <li>148 <a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-queue.rst?plain=1"149 rel="nofollow">Show source150 </a>151 </li>152 153 </ul>154 </div>155 </nav>156 </div>157</div>158 159 160 <div class="related" role="navigation" aria-label="Related">161 <h3>Navigation</h3>162 <ul>163 <li class="right" style="margin-right: 10px">164 <a href="../genindex.html" title="General Index"165 accesskey="I">index</a></li>166 <li class="right" >167 <a href="../py-modindex.html" title="Python Module Index"168 >modules</a> |</li>169 <li class="right" >170 <a href="asyncio-exceptions.html" title="Exceptions"171 accesskey="N">next</a> |</li>172 <li class="right" >173 <a href="asyncio-subprocess.html" title="Subprocesses"174 accesskey="P">previous</a> |</li>175 176 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>177 <li><a href="https://www.python.org/">Python</a> »</li>178 <li class="switchers">179 <div class="language_switcher_placeholder"></div>180 <div class="version_switcher_placeholder"></div>181 </li>182 <li>183 184 </li>185 <li id="cpython-language-and-version">186 <a href="../index.html">3.15.0a6 Documentation</a> »187 </li>188 189 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>190 <li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>191 <li class="nav-item nav-item-3"><a href="asyncio.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> »</li>192 <li class="nav-item nav-item-this"><a href="">Queues</a></li>193 <li class="right">194 195 196 <div class="inline-search" role="search">197 <form class="inline-search" action="../search.html" method="get">198 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">199 <input type="submit" value="Go">200 </form>201 </div>202 |203 </li>204 <li class="right">205<label class="theme-selector-label">206 Theme207 <select class="theme-selector" oninput="activateTheme(this.value)">208 <option value="auto" selected>Auto</option>209 <option value="light">Light</option>210 <option value="dark">Dark</option>211 </select>212</label> |</li>213 214 </ul>215 </div> 216 217 <div class="document">218 <div class="documentwrapper">219 <div class="bodywrapper">220 <div class="body" role="main">221 222 <section id="queues">223<span id="asyncio-queues"></span><h1>Queues<a class="headerlink" href="#queues" title="Link to this heading">¶</a></h1>224<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/asyncio/queues.py">Lib/asyncio/queues.py</a></p>225<hr class="docutils" />226<p>asyncio queues are designed to be similar to classes of the227<a class="reference internal" href="queue.html#module-queue" title="queue: A synchronized queue class."><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code></a> module. Although asyncio queues are not thread-safe,228they are designed to be used specifically in async/await code.</p>229<p>Note that methods of asyncio queues don’t have a <em>timeout</em> parameter;230use <a class="reference internal" href="asyncio-task.html#asyncio.wait_for" title="asyncio.wait_for"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.wait_for()</span></code></a> function to do queue operations with a231timeout.</p>232<p>See also the <a class="reference internal" href="#examples">Examples</a> section below.</p>233<section id="queue">234<h2>Queue<a class="headerlink" href="#queue" title="Link to this heading">¶</a></h2>235<dl class="py class">236<dt class="sig sig-object py" id="asyncio.Queue">237<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">Queue</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">maxsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue" title="Link to this definition">¶</a></dt>238<dd><p>A first in, first out (FIFO) queue.</p>239<p>If <em>maxsize</em> is less than or equal to zero, the queue size is240infinite. If it is an integer greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, then241<code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">put()</span></code> blocks when the queue reaches <em>maxsize</em>242until an item is removed by <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a>.</p>243<p>Unlike the standard library threading <a class="reference internal" href="queue.html#module-queue" title="queue: A synchronized queue class."><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code></a>, the size of244the queue is always known and can be returned by calling the245<a class="reference internal" href="#asyncio.Queue.qsize" title="asyncio.Queue.qsize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">qsize()</span></code></a> method.</p>246<div class="versionchanged">247<p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the <em>loop</em> parameter.</p>248</div>249<p>This class is <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading"><span class="std std-ref">not thread safe</span></a>.</p>250<dl class="py attribute">251<dt class="sig sig-object py" id="asyncio.Queue.maxsize">252<span class="sig-name descname"><span class="pre">maxsize</span></span><a class="headerlink" href="#asyncio.Queue.maxsize" title="Link to this definition">¶</a></dt>253<dd><p>Number of items allowed in the queue.</p>254</dd></dl>255 256<dl class="py method">257<dt class="sig sig-object py" id="asyncio.Queue.empty">258<span class="sig-name descname"><span class="pre">empty</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.empty" title="Link to this definition">¶</a></dt>259<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the queue is empty, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>260</dd></dl>261 262<dl class="py method">263<dt class="sig sig-object py" id="asyncio.Queue.full">264<span class="sig-name descname"><span class="pre">full</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.full" title="Link to this definition">¶</a></dt>265<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if there are <a class="reference internal" href="#asyncio.Queue.maxsize" title="asyncio.Queue.maxsize"><code class="xref py py-attr docutils literal notranslate"><span class="pre">maxsize</span></code></a> items in the queue.</p>266<p>If the queue was initialized with <code class="docutils literal notranslate"><span class="pre">maxsize=0</span></code> (the default),267then <code class="xref py py-meth docutils literal notranslate"><span class="pre">full()</span></code> never returns <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>268</dd></dl>269 270<dl class="py method">271<dt class="sig sig-object py" id="asyncio.Queue.get">272<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.get" title="Link to this definition">¶</a></dt>273<dd><p>Remove and return an item from the queue. If queue is empty,274wait until an item is available.</p>275<p>Raises <a class="reference internal" href="#asyncio.QueueShutDown" title="asyncio.QueueShutDown"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code></a> if the queue has been shut down and276is empty, or if the queue has been shut down immediately.</p>277</dd></dl>278 279<dl class="py method">280<dt class="sig sig-object py" id="asyncio.Queue.get_nowait">281<span class="sig-name descname"><span class="pre">get_nowait</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.get_nowait" title="Link to this definition">¶</a></dt>282<dd><p>Return an item if one is immediately available, else raise283<a class="reference internal" href="#asyncio.QueueEmpty" title="asyncio.QueueEmpty"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueEmpty</span></code></a>.</p>284</dd></dl>285 286<dl class="py method">287<dt class="sig sig-object py" id="asyncio.Queue.join">288<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">join</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.join" title="Link to this definition">¶</a></dt>289<dd><p>Block until all items in the queue have been received and processed.</p>290<p>The count of unfinished tasks goes up whenever an item is added291to the queue. The count goes down whenever a consumer coroutine calls292<a class="reference internal" href="#asyncio.Queue.task_done" title="asyncio.Queue.task_done"><code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code></a> to indicate that the item was retrieved and all293work on it is complete. When the count of unfinished tasks drops294to zero, <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> unblocks.</p>295</dd></dl>296 297<dl class="py method">298<dt class="sig sig-object py" id="asyncio.Queue.put">299<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">put</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">item</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.put" title="Link to this definition">¶</a></dt>300<dd><p>Put an item into the queue. If the queue is full, wait until a301free slot is available before adding the item.</p>302<p>Raises <a class="reference internal" href="#asyncio.QueueShutDown" title="asyncio.QueueShutDown"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code></a> if the queue has been shut down.</p>303</dd></dl>304 305<dl class="py method">306<dt class="sig sig-object py" id="asyncio.Queue.put_nowait">307<span class="sig-name descname"><span class="pre">put_nowait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">item</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.put_nowait" title="Link to this definition">¶</a></dt>308<dd><p>Put an item into the queue without blocking.</p>309<p>If no free slot is immediately available, raise <a class="reference internal" href="#asyncio.QueueFull" title="asyncio.QueueFull"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueFull</span></code></a>.</p>310</dd></dl>311 312<dl class="py method">313<dt class="sig sig-object py" id="asyncio.Queue.qsize">314<span class="sig-name descname"><span class="pre">qsize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.qsize" title="Link to this definition">¶</a></dt>315<dd><p>Return the number of items in the queue.</p>316</dd></dl>317 318<dl class="py method">319<dt class="sig sig-object py" id="asyncio.Queue.shutdown">320<span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">immediate</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.shutdown" title="Link to this definition">¶</a></dt>321<dd><p>Put a <code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code> instance into a shutdown mode.</p>322<p>The queue can no longer grow.323Future calls to <a class="reference internal" href="#asyncio.Queue.put" title="asyncio.Queue.put"><code class="xref py py-meth docutils literal notranslate"><span class="pre">put()</span></code></a> raise <a class="reference internal" href="#asyncio.QueueShutDown" title="asyncio.QueueShutDown"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code></a>.324Currently blocked callers of <code class="xref py py-meth docutils literal notranslate"><span class="pre">put()</span></code> will be unblocked325and will raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code> in the formerly awaiting task.</p>326<p>If <em>immediate</em> is false (the default), the queue can be wound327down normally with <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> calls to extract tasks328that have already been loaded.</p>329<p>And if <a class="reference internal" href="#asyncio.Queue.task_done" title="asyncio.Queue.task_done"><code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code></a> is called for each remaining task, a330pending <a class="reference internal" href="#asyncio.Queue.join" title="asyncio.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> will be unblocked normally.</p>331<p>Once the queue is empty, future calls to <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> will332raise <a class="reference internal" href="#asyncio.QueueShutDown" title="asyncio.QueueShutDown"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code></a>.</p>333<p>If <em>immediate</em> is true, the queue is terminated immediately.334The queue is drained to be completely empty and the count335of unfinished tasks is reduced by the number of tasks drained.336If unfinished tasks is zero, callers of <a class="reference internal" href="#asyncio.Queue.join" title="asyncio.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>337are unblocked. Also, blocked callers of <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a>338are unblocked and will raise <a class="reference internal" href="#asyncio.QueueShutDown" title="asyncio.QueueShutDown"><code class="xref py py-exc docutils literal notranslate"><span class="pre">QueueShutDown</span></code></a> because the339queue is empty.</p>340<p>Use caution when using <a class="reference internal" href="#asyncio.Queue.join" title="asyncio.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> with <em>immediate</em> set341to true. This unblocks the join even when no work has been done342on the tasks, violating the usual invariant for joining a queue.</p>343<div class="versionadded">344<p><span class="versionmodified added">Added in version 3.13.</span></p>345</div>346</dd></dl>347 348<dl class="py method">349<dt class="sig sig-object py" id="asyncio.Queue.task_done">350<span class="sig-name descname"><span class="pre">task_done</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Queue.task_done" title="Link to this definition">¶</a></dt>351<dd><p>Indicate that a formerly enqueued work item is complete.</p>352<p>Used by queue consumers. For each <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> used to353fetch a work item, a subsequent call to <code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code> tells the354queue that the processing on the work item is complete.</p>355<p>If a <a class="reference internal" href="#asyncio.Queue.join" title="asyncio.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> is currently blocking, it will resume when all356items have been processed (meaning that a <code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code>357call was received for every item that had been <a class="reference internal" href="#asyncio.Queue.put" title="asyncio.Queue.put"><code class="xref py py-meth docutils literal notranslate"><span class="pre">put()</span></code></a>358into the queue).</p>359<p>Raises <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if called more times than there were360items placed in the queue.</p>361</dd></dl>362 363</dd></dl>364 365</section>366<section id="priority-queue">367<h2>Priority Queue<a class="headerlink" href="#priority-queue" title="Link to this heading">¶</a></h2>368<dl class="py class">369<dt class="sig sig-object py" id="asyncio.PriorityQueue">370<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">PriorityQueue</span></span><a class="headerlink" href="#asyncio.PriorityQueue" title="Link to this definition">¶</a></dt>371<dd><p>A variant of <a class="reference internal" href="#asyncio.Queue" title="asyncio.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a>; retrieves entries in priority order372(lowest first).</p>373<p>Entries are typically tuples of the form374<code class="docutils literal notranslate"><span class="pre">(priority_number,</span> <span class="pre">data)</span></code>.</p>375</dd></dl>376 377</section>378<section id="lifo-queue">379<h2>LIFO Queue<a class="headerlink" href="#lifo-queue" title="Link to this heading">¶</a></h2>380<dl class="py class">381<dt class="sig sig-object py" id="asyncio.LifoQueue">382<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">LifoQueue</span></span><a class="headerlink" href="#asyncio.LifoQueue" title="Link to this definition">¶</a></dt>383<dd><p>A variant of <a class="reference internal" href="#asyncio.Queue" title="asyncio.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a> that retrieves most recently added384entries first (last in, first out).</p>385</dd></dl>386 387</section>388<section id="exceptions">389<h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>390<dl class="py exception">391<dt class="sig sig-object py" id="asyncio.QueueEmpty">392<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">QueueEmpty</span></span><a class="headerlink" href="#asyncio.QueueEmpty" title="Link to this definition">¶</a></dt>393<dd><p>This exception is raised when the <a class="reference internal" href="#asyncio.Queue.get_nowait" title="asyncio.Queue.get_nowait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_nowait()</span></code></a> method394is called on an empty queue.</p>395</dd></dl>396 397<dl class="py exception">398<dt class="sig sig-object py" id="asyncio.QueueFull">399<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">QueueFull</span></span><a class="headerlink" href="#asyncio.QueueFull" title="Link to this definition">¶</a></dt>400<dd><p>Exception raised when the <a class="reference internal" href="#asyncio.Queue.put_nowait" title="asyncio.Queue.put_nowait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">put_nowait()</span></code></a> method is called401on a queue that has reached its <em>maxsize</em>.</p>402</dd></dl>403 404<dl class="py exception">405<dt class="sig sig-object py" id="asyncio.QueueShutDown">406<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">QueueShutDown</span></span><a class="headerlink" href="#asyncio.QueueShutDown" title="Link to this definition">¶</a></dt>407<dd><p>Exception raised when <a class="reference internal" href="#asyncio.Queue.put" title="asyncio.Queue.put"><code class="xref py py-meth docutils literal notranslate"><span class="pre">put()</span></code></a> or <a class="reference internal" href="#asyncio.Queue.get" title="asyncio.Queue.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> is408called on a queue which has been shut down.</p>409<div class="versionadded">410<p><span class="versionmodified added">Added in version 3.13.</span></p>411</div>412</dd></dl>413 414</section>415<section id="examples">416<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>417<p id="asyncio-example-queue-dist">Queues can be used to distribute workload between several418concurrent tasks:</p>419<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>420<span class="kn">import</span><span class="w"> </span><span class="nn">random</span>421<span class="kn">import</span><span class="w"> </span><span class="nn">time</span>422 423 424<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">worker</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">queue</span><span class="p">):</span>425 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>426 <span class="c1"># Get a "work item" out of the queue.</span>427 <span class="n">sleep_for</span> <span class="o">=</span> <span class="k">await</span> <span class="n">queue</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>428 429 <span class="c1"># Sleep for the "sleep_for" seconds.</span>430 <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">sleep_for</span><span class="p">)</span>431 432 <span class="c1"># Notify the queue that the "work item" has been processed.</span>433 <span class="n">queue</span><span class="o">.</span><span class="n">task_done</span><span class="p">()</span>434 435 <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s1"> has slept for </span><span class="si">{</span><span class="n">sleep_for</span><span class="si">:</span><span class="s1">.2f</span><span class="si">}</span><span class="s1"> seconds'</span><span class="p">)</span>436 437 438<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>439 <span class="c1"># Create a queue that we will use to store our "workload".</span>440 <span class="n">queue</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Queue</span><span class="p">()</span>441 442 <span class="c1"># Generate random timings and put them into the queue.</span>443 <span class="n">total_sleep_time</span> <span class="o">=</span> <span class="mi">0</span>444 <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">):</span>445 <span class="n">sleep_for</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="mf">0.05</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">)</span>446 <span class="n">total_sleep_time</span> <span class="o">+=</span> <span class="n">sleep_for</span>447 <span class="n">queue</span><span class="o">.</span><span class="n">put_nowait</span><span class="p">(</span><span class="n">sleep_for</span><span class="p">)</span>448 449 <span class="c1"># Create three worker tasks to process the queue concurrently.</span>450 <span class="n">tasks</span> <span class="o">=</span> <span class="p">[]</span>451 <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">):</span>452 <span class="n">task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">worker</span><span class="p">(</span><span class="sa">f</span><span class="s1">'worker-</span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="s1">'</span><span class="p">,</span> <span class="n">queue</span><span class="p">))</span>453 <span class="n">tasks</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>454 455 <span class="c1"># Wait until the queue is fully processed.</span>456 <span class="n">started_at</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">monotonic</span><span class="p">()</span>457 <span class="k">await</span> <span class="n">queue</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>458 <span class="n">total_slept_for</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">monotonic</span><span class="p">()</span> <span class="o">-</span> <span class="n">started_at</span>459 460 <span class="c1"># Cancel our worker tasks.</span>461 <span class="k">for</span> <span class="n">task</span> <span class="ow">in</span> <span class="n">tasks</span><span class="p">:</span>462 <span class="n">task</span><span class="o">.</span><span class="n">cancel</span><span class="p">()</span>463 <span class="c1"># Wait until all worker tasks are cancelled.</span>464 <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">gather</span><span class="p">(</span><span class="o">*</span><span class="n">tasks</span><span class="p">,</span> <span class="n">return_exceptions</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>465 466 <span class="nb">print</span><span class="p">(</span><span class="s1">'===='</span><span class="p">)</span>467 <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'3 workers slept in parallel for </span><span class="si">{</span><span class="n">total_slept_for</span><span class="si">:</span><span class="s1">.2f</span><span class="si">}</span><span class="s1"> seconds'</span><span class="p">)</span>468 <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'total expected sleep time: </span><span class="si">{</span><span class="n">total_sleep_time</span><span class="si">:</span><span class="s1">.2f</span><span class="si">}</span><span class="s1"> seconds'</span><span class="p">)</span>469 470 471<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>472</pre></div>473</div>474</section>475</section>476 477 478 <div class="clearer"></div>479 </div>480 </div>481 </div>482 <div class="sphinxsidebar" role="navigation" aria-label="Main">483 <div class="sphinxsidebarwrapper">484 <div>485 <h3><a href="../contents.html">Table of Contents</a></h3>486 <ul>487<li><a class="reference internal" href="#">Queues</a><ul>488<li><a class="reference internal" href="#queue">Queue</a></li>489<li><a class="reference internal" href="#priority-queue">Priority Queue</a></li>490<li><a class="reference internal" href="#lifo-queue">LIFO Queue</a></li>491<li><a class="reference internal" href="#exceptions">Exceptions</a></li>492<li><a class="reference internal" href="#examples">Examples</a></li>493</ul>494</li>495</ul>496 497 </div>498 <div>499 <h4>Previous topic</h4>500 <p class="topless"><a href="asyncio-subprocess.html"501 title="previous chapter">Subprocesses</a></p>502 </div>503 <div>504 <h4>Next topic</h4>505 <p class="topless"><a href="asyncio-exceptions.html"506 title="next chapter">Exceptions</a></p>507 </div>508 <script>509 document.addEventListener('DOMContentLoaded', () => {510 const title = document.querySelector('meta[property="og:title"]').content;511 const elements = document.querySelectorAll('.improvepage');512 const pageurl = window.location.href.split('?')[0];513 elements.forEach(element => {514 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));515 url.searchParams.set('pagetitle', title);516 url.searchParams.set('pageurl', pageurl);517 url.searchParams.set('pagesource', "library/asyncio-queue.rst");518 element.href = url.toString();519 });520 });521 </script>522 <div role="note" aria-label="source link">523 <h3>This page</h3>524 <ul class="this-page-menu">525 <li><a href="../bugs.html">Report a bug</a></li>526 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>527 <li>528 <a href="https://github.com/python/cpython/blob/main/Doc/library/asyncio-queue.rst?plain=1"529 rel="nofollow">Show source530 </a>531 </li>532 533 </ul>534 </div>535 </div>536<div id="sidebarbutton" title="Collapse sidebar">537<span>«</span>538</div>539 540 </div>541 <div class="clearer"></div>542 </div> 543 <div class="related" role="navigation" aria-label="Related">544 <h3>Navigation</h3>545 <ul>546 <li class="right" style="margin-right: 10px">547 <a href="../genindex.html" title="General Index"548 >index</a></li>549 <li class="right" >550 <a href="../py-modindex.html" title="Python Module Index"551 >modules</a> |</li>552 <li class="right" >553 <a href="asyncio-exceptions.html" title="Exceptions"554 >next</a> |</li>555 <li class="right" >556 <a href="asyncio-subprocess.html" title="Subprocesses"557 >previous</a> |</li>558 559 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>560 <li><a href="https://www.python.org/">Python</a> »</li>561 <li class="switchers">562 <div class="language_switcher_placeholder"></div>563 <div class="version_switcher_placeholder"></div>564 </li>565 <li>566 567 </li>568 <li id="cpython-language-and-version">569 <a href="../index.html">3.15.0a6 Documentation</a> »570 </li>571 572 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>573 <li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>574 <li class="nav-item nav-item-3"><a href="asyncio.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> »</li>575 <li class="nav-item nav-item-this"><a href="">Queues</a></li>576 <li class="right">577 578 579 <div class="inline-search" role="search">580 <form class="inline-search" action="../search.html" method="get">581 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">582 <input type="submit" value="Go">583 </form>584 </div>585 |586 </li>587 <li class="right">588<label class="theme-selector-label">589 Theme590 <select class="theme-selector" oninput="activateTheme(this.value)">591 <option value="auto" selected>Auto</option>592 <option value="light">Light</option>593 <option value="dark">Dark</option>594 </select>595</label> |</li>596 597 </ul>598 </div> 599 <div class="footer">600 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.601 <br>602 This page is licensed under the Python Software Foundation License Version 2.603 <br>604 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.605 <br>606 607 See <a href="/license.html">History and License</a> for more information.<br>608 609 610 <br>611 612 The Python Software Foundation is a non-profit corporation.613<a href="https://www.python.org/psf/donations/">Please donate.</a>614<br>615 <br>616 Last updated on Mar 10, 2026 (08:58 UTC).617 618 <a href="/bugs.html">Found a bug</a>?619 620 <br>621 622 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.623 </div>624 625 </body>626</html>