<p>When run, this will print <codeclass="docutils literal notranslate"><spanclass="pre">"before</span><spanclass="pre">call</span><spanclass="pre">..."</span></code>, after which the <codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> gets to work
for however long time. Only once that is done, the system prints <codeclass="docutils literal notranslate"><spanclass="pre">"after</span><spanclass="pre">call</span><spanclass="pre">..."</span></code>. Easy and
logical to follow. Most of Evennia work in this way and often it’s important that commands get
executed in the same strict order they were coded.</p>
<p>Evennia, via Twisted, is a single-process multi-user server. In simple terms this means that it
swiftly switches between dealing with player input so quickly that each player feels like they do
things at the same time. This is a clever illusion however: If one user, say, runs a command
containing that <codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code>, <em>all</em> other players are effectively forced to wait until it
finishes.</p>
<p>Now, it should be said that on a modern computer system this is rarely an issue. Very few commands
run so long that other users notice it. And as mentioned, most of the time you <em>want</em> to enforce
all commands to occur in strict sequence.</p>
<p>When delays do become noticeable and you don’t care in which order the command actually completes,
you can run it <em>asynchronously</em>. This makes use of the <codeclass="docutils literal notranslate"><spanclass="pre">run_async()</span></code> function in
<p>Where <codeclass="docutils literal notranslate"><spanclass="pre">function</span></code> will be called asynchronously with <codeclass="docutils literal notranslate"><spanclass="pre">*args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code>. Example:</p>
<p>Now, when running this you will find that the program will not wait around for
<codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> to finish. In fact you will see <codeclass="docutils literal notranslate"><spanclass="pre">"before</span><spanclass="pre">call</span><spanclass="pre">..."</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">"after</span><spanclass="pre">call</span><spanclass="pre">..."</span></code>
printed out right away. The long-running function will run in the background and you (and other
<h2>Customizing asynchronous operation<aclass="headerlink"href="#customizing-asynchronous-operation"title="Permalink to this headline">¶</a></h2>
<p>A complication with using asynchronous calls is what to do with the result from that call. What if
<codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> returns a value that you need? It makes no real sense to put any lines of
code after the call to try to deal with the result from <codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> above - as we saw
the <codeclass="docutils literal notranslate"><spanclass="pre">"after</span><spanclass="pre">call</span><spanclass="pre">..."</span></code> got printed long before <codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> was finished, making that
line quite pointless for processing any data from the function. Instead one has to use <em>callbacks</em>.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">utils.run_async</span></code> takes reserved kwargs that won’t be passed into the long-running function:</p>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_return(r)</span></code> (the <em>callback</em>) is called when the asynchronous function (<codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code>
above) finishes successfully. The argument <codeclass="docutils literal notranslate"><spanclass="pre">r</span></code> will then be the return value of that function (or
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_return_kwargs</span></code> - an optional dictionary that will be fed as keyword arguments to the
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_err(e)</span></code> (the <em>errback</em>) is called if the asynchronous function fails and raises an exception.
This exception is passed to the errback wrapped in a <em>Failure</em> object <codeclass="docutils literal notranslate"><spanclass="pre">e</span></code>. If you do not supply an
errback of your own, Evennia will automatically add one that silently writes errors to the evennia
log. An example of an errback is found below:</p></li>
<spanclass="k">print</span><spanclass="p">(</span><spanclass="s2">"There was an error:"</span><spanclass="p">,</span><spanclass="nb">str</span><spanclass="p">(</span><spanclass="n">e</span><spanclass="p">))</span>
</pre></div>
</td></tr></table></div>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_err_kwargs</span></code> - an optional dictionary that will be fed as keyword arguments to the <codeclass="docutils literal notranslate"><spanclass="pre">at_err</span></code>
errback.</p></li>
</ul>
<p>An example of making an asynchronous call from inside a <aclass="reference internal"href="Commands.html"><spanclass="doc">Command</span></a> definition:</p>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"The final value is </span><spanclass="si">%s</span><spanclass="s2">"</span><spanclass="o">%</span><spanclass="n">r</span><spanclass="p">)</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"There was an error: </span><spanclass="si">%s</span><spanclass="s2">"</span><spanclass="o">%</span><spanclass="n">e</span><spanclass="p">)</span>
<spanclass="c1"># do the async call, setting all callbacks</span>
<p>That’s it - from here on we can forget about <codeclass="docutils literal notranslate"><spanclass="pre">long_running_function</span></code> and go on with what else need
to be done. <em>Whenever</em> it finishes, the <codeclass="docutils literal notranslate"><spanclass="pre">at_return_function</span></code> function will be called and the final
pop up for us to see. If not we will see an error message.</p>
</div>
<divclass="section"id="delay">
<h2>delay<aclass="headerlink"href="#delay"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">delay</span></code> function is a much simpler sibling to <codeclass="docutils literal notranslate"><spanclass="pre">run_async</span></code>. It is in fact just a way to delay the
execution of a command until a future time. This is equivalent to something like <codeclass="docutils literal notranslate"><spanclass="pre">time.sleep()</span></code>
except delay is asynchronous while <codeclass="docutils literal notranslate"><spanclass="pre">sleep</span></code> would lock the entire server for the duration of the
<p>As of Evennia 0.9, the <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> [decorator](https://realpython.com/primer-on-python-
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Getting ready to wait ..."</span><spanclass="p">)</span>
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Now 5 seconds have passed."</span><spanclass="p">)</span>
<spanclass="n">response</span><spanclass="o">=</span><spanclass="k">yield</span><spanclass="p">(</span><spanclass="s2">"Do you want to wait another 5 secs?"</span><spanclass="p">)</span>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> decorator gives the function the ability to pause. The use
of <codeclass="docutils literal notranslate"><spanclass="pre">yield(seconds)</span></code> will do just that - it will asynchronously pause for the
number of seconds given before continuing. This is technically equivalent to
using <codeclass="docutils literal notranslate"><spanclass="pre">call_async</span></code> with a callback that continues after 5 secs. But the code
with <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> is a little easier to follow.</p>
<p>Within the <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> function, the <codeclass="docutils literal notranslate"><spanclass="pre">response</span><spanclass="pre">=</span><spanclass="pre">yield("question")</span></code> question
allows you to ask the user for input. You can then process the input, just like
you would if you used the Python <codeclass="docutils literal notranslate"><spanclass="pre">input</span></code> function. There is one caveat to this
functionality though - <em>it will only work if the function/method has an
argument named exactly <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code></em>. This is because internally Evennia will look
for the <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> argument and treat that as the source of input.</p>
<p>All of this makes the <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> decorator very useful. But it comes with a
few caveats. Notably, decorating a function/method with <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code> turns it
into a Python <aclass="reference external"href="https://wiki.python.org/moin/Generators">generator</a>. The most
common issue is that you cannot use <codeclass="docutils literal notranslate"><spanclass="pre">return</span><spanclass="pre"><value></span></code> from a generator (just an
empty <codeclass="docutils literal notranslate"><spanclass="pre">return</span></code> works). To return a value from a function/method you have decorated
with <codeclass="docutils literal notranslate"><spanclass="pre">@interactive</span></code>, you must instead use a special Twisted function
<codeclass="docutils literal notranslate"><spanclass="pre">twisted.internet.defer.returnValue</span></code>. Evennia also makes this function
conveniently available from <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils</span></code>:</p>
<h2>Assorted notes<aclass="headerlink"href="#assorted-notes"title="Permalink to this headline">¶</a></h2>
<p>Overall, be careful with choosing when to use asynchronous calls. It is mainly useful for large
administration operations that have no direct influence on the game world (imports and backup
operations come to mind). Since there is no telling exactly when an asynchronous call actually ends,
using them for in-game commands is to potentially invite confusion and inconsistencies (and very
hard-to-reproduce bugs).</p>
<p>The very first synchronous example above is not <em>really</em> correct in the case of Twisted, which is
inherently an asynchronous server. Notably you might find that you will <em>not</em> see the first <codeclass="docutils literal notranslate"><spanclass="pre">before</span><spanclass="pre">call</span><spanclass="pre">...</span></code> text being printed out right away. Instead all texts could end up being delayed until
after the long-running process finishes. So all commands will retain their relative order as
expected, but they may appear with delays or in groups.</p>
</div>
<divclass="section"id="further-reading">
<h2>Further reading<aclass="headerlink"href="#further-reading"title="Permalink to this headline">¶</a></h2>
<p>Technically, <codeclass="docutils literal notranslate"><spanclass="pre">run_async</span></code> is just a very thin and simplified wrapper around a
