Ticket #4568: core-lowlevel.xhtml.patch

File core-lowlevel.xhtml.patch, 17.1 KB (added by jdb, 6 years ago)

Improved the rst output for articles in the "Low-Level Networking and Event Loop" section of the core howto

  • doc/core/howto/defer.xhtml

    diff --git a/doc/core/howto/defer.xhtml b/doc/core/howto/defer.xhtml
    index 21da54e..2a131d3 100644
    a b code.</li> 
    3838<h2>Deferreds</h2>
    3939
    4040<p>Twisted uses the <code class="API"
    41 base="twisted.internet.defer">Deferred</code> object to manage the callback
    42 sequence. The client application attaches a series of functions to the
    43 deferred to be called in order when the results of the asychronous request are
    44 available (this series of functions is known as a series of
    45 <strong>callbacks</strong>, or a <strong>callback chain</strong>), together
    46 with a series of functions to be called if there is an error in the
    47 asychronous request (known as a series of <strong>errbacks</strong> or an
    48 <strong>errback chain</strong>). The asychronous library code calls the first
    49 callback when the result is available, or the first errback when an error
    50 occurs, and the <code>Deferred</code> object then hands the results of each
    51 callback or errback function to the next function in the chain.</p>
     41base="twisted.internet.defer">Deferred</code> object to manage the
     42callback sequence. The client application attaches a series of
     43functions to the deferred to be called in order when the results of
     44the asychronous request are available (this series of functions is
     45known as a series of <strong>callbacks</strong>, or a <strong>callback
     46chain</strong>), together with a series of functions to be called if
     47there is an error in the asychronous request (known as a series
     48of <strong>errbacks</strong> or an <strong>errback
     49chain</strong>). The asychronous library code calls the first callback
     50when the result is available, or the first errback when an error
     51occurs, and the <code>Deferred</code> object then hands the results of
     52each callback or errback function to the next function in the
     53chain.</p>
    5254
    5355<h2>Callbacks</h2>
    5456
    d.addCallbacks(callback1, errback1) # C 
    296298d.addCallbacks(callback2, errback2) 
    297299</pre>
    298300
    299 <p>If an error occurs in <code class="python">callback1</code>, then for Case 1
    300 <code class="python">errback1</code> will be called with the failure. For Case
    301 2, <code class="python">errback2</code> will be called. Be careful with your
    302 callbacks and errbacks.</p>
     301<p>If an error occurs in <code class="python">callback1</code>, then
     302for Case 1 <code class="python">errback1</code> will be called with
     303the failure. For Case 2, <code class="python">errback2</code> will be
     304called. Be careful with your callbacks and errbacks.</p>
    303305
    304 <p>What this means in a practical sense is in Case 1, &quot;A&quot; will
    305 handle a success condition from <code>getDeferredFromSomewhere</code>, and
    306 &quot;B&quot; will handle any errors that occur <em>from either the upstream
    307 source, or that occur in 'A'</em>.  In Case 2, &quot;C&quot;'s errback1
    308 <em>will only handle an error condition raised by
    309 <code>getDeferredFromSomewhere</code></em>, it will not do any handling of
    310 errors raised in callback1.</p>
     306<p>What this means in a practical sense is in Case 1, &quot;A&quot;
     307will handle a success condition
     308from <code>getDeferredFromSomewhere</code>, and &quot;B&quot; will
     309handle any errors that occur <em>from either the upstream source, or
     310that occur in 'A'</em>.  In Case 2, &quot;C&quot;'s errback1 <em>will
     311only handle an error condition raised
     312by </em> <code>getDeferredFromSomewhere</code>, it will not do any
     313handling of errors raised in callback1.</p>
    311314
    312315
    313316<h3>Unhandled Errors</h3>
    def asynchronousIsValidUser(d, user): 
    390393    return d
    391394</pre>
    392395
    393 <p> Our original implementation of <code>authenticateUser</code> expected
    394 <code>isValidUser</code> to be synchronous, but now we need to change it to handle both
    395 synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we
    396 use <code class="API" base="twisted.internet.defer">maybeDeferred</code> to
    397 call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,
    398 even if <code>isValidUser</code> is a synchronous function:
     396<p> Our original implementation of <code>authenticateUser</code>
     397expected <code>isValidUser</code> to be synchronous, but now we need
     398to change it to handle both synchronous and asynchronous
     399implementations of <code>isValidUser</code>. For this, we
     400use <code class="API"
     401base="twisted.internet.defer">maybeDeferred</code> to
     402call <code>isValidUser</code>, ensuring that the result
     403of <code>isValidUser</code> is a Deferred, even
     404if <code>isValidUser</code> is a synchronous function:
    399405</p>
    400406
    401407<pre class="python">
    def authenticateUser(isValidUser, user): 
    413419</pre>
    414420
    415421<p>
    416 Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or
    417 <code>asynchronousIsValidUser</code>.
     422Now <code>isValidUser</code> could be
     423either <code>synchronousIsValidUser</code>
     424or <code>asynchronousIsValidUser</code>.
    418425</p>
    419426
    420427<p>It is also possible to modify <code>synchronousIsValidUser</code> to return
    the Deferreds you want it to wait for:</p> 
    436443dl = defer.DeferredList([deferred1, deferred2, deferred3])
    437444</pre>
    438445
    439 <p>You can now treat the DeferredList like an ordinary Deferred; you can call
    440 <code>addCallbacks</code> and so on.  The DeferredList will call its callback
    441 when all the deferreds have completed.  The callback will be called with a list
    442 of the results of the Deferreds it contains, like so:</p>
     446<p>You can now treat the DeferredList like an ordinary Deferred; you
     447can call <code>addCallbacks</code> and so on.  The DeferredList will
     448call its callback when all the deferreds have completed.  The callback
     449will be called with a list of the results of the Deferreds it
     450contains, like so:</p>
    443451
    444452<pre class="python">
    445453def printResult(result):
    deferred2.callback("two") 
    518526
    519527<h3>Other behaviours</h3>
    520528
    521 <p>DeferredList accepts three keyword arguments that modify its behaviour:
    522 <code>fireOnOneCallback</code>, <code>fireOnOneErrback</code> and
    523 <code>consumeErrors</code>.  If <code>fireOnOneCallback</code> is set, the
    524 DeferredList will immediately call its callback as soon as any of its Deferreds
    525 call their callback.  Similarly, <code>fireOnOneErrback</code> will call errback
    526 as soon as any of the Deferreds call their errback.  Note that DeferredList is
    527 still one-shot, like ordinary Deferreds, so after a callback or errback has been
    528 called the DeferredList will do nothing further (it will just silently ignore
    529 any other results from its Deferreds).</p>
     529<p>DeferredList accepts three keyword arguments that modify its
     530behaviour: <code>fireOnOneCallback</code>, <code>fireOnOneErrback</code>
     531and <code>consumeErrors</code>.  If <code>fireOnOneCallback</code> is
     532set, the DeferredList will immediately call its callback as soon as
     533any of its Deferreds call their callback.
     534Similarly, <code>fireOnOneErrback</code> will call errback as soon as
     535any of the Deferreds call their errback.  Note that DeferredList is
     536still one-shot, like ordinary Deferreds, so after a callback or
     537errback has been called the DeferredList will do nothing further (it
     538will just silently ignore any other results from its Deferreds).</p>
    530539
    531540<p>The <code>fireOnOneErrback</code> option is particularly useful when you
    532541want to wait for all the results if everything succeeds, but also want to know
    533542immediately if something fails.</p>
    534543
    535 <p>The <code>consumeErrors</code> argument will stop the DeferredList from
    536 propagating any errors along the callback chains of any Deferreds it contains
    537 (usually creating a DeferredList has no effect on the results passed along the
    538 callbacks and errbacks of their Deferreds).  Stopping errors at the DeferredList
    539 with this option will prevent <q>Unhandled error in Deferred</q> warnings from
    540 the Deferreds it contains without needing to add extra errbacks<span
    541 class="footnote">Unless of course a later callback starts a fresh error &mdash;
    542 but as we've already noted, adding callbacks to a Deferred after its used in a
    543 DeferredList is confusing and usually avoided.</span>.  Passing a true value
    544 for the <code>consumeErrors</code> parameter will not change the behavior of
    545 <code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
     544<p>The <code>consumeErrors</code> argument will stop the DeferredList
     545from propagating any errors along the callback chains of any Deferreds
     546it contains (usually creating a DeferredList has no effect on the
     547results passed along the callbacks and errbacks of their Deferreds).
     548Stopping errors at the DeferredList with this option will
     549prevent <q>Unhandled error in Deferred</q> warnings from the Deferreds
     550it contains without needing to add extra
     551errbacks<span class="footnote">Unless of course a later callback
     552starts a fresh error &mdash; but as we've already noted, adding
     553callbacks to a Deferred after its used in a DeferredList is confusing
     554and usually avoided.</span>.  Passing a true value for
     555the <code>consumeErrors</code> parameter will not change the behavior
     556of <code>fireOnOneCallback</code>
     557or <code>fireOnOneErrback</code>.</p>
    546558
    547559<a name="class"></a>
    548560
    Deferred returned by a function. It is not meant to be a 
    553565substitute for the docstrings in the Deferred class, but can provide guidelines
    554566for its use.</p>
    555567
    556 <p>There is a parallel overview of functions used by the Deferred's
    557 <em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
     568<p>There is a parallel overview of functions used by the
     569Deferred's <em>creator</em>
     570in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
    558571
    559572<h3>Basic Callback Functions</h3>
    560573
  • doc/core/howto/deferredindepth.xhtml

    diff --git a/doc/core/howto/deferredindepth.xhtml b/doc/core/howto/deferredindepth.xhtml
    index 9a7edfc..479a601 100644
    a b  
    1010<h2>Introduction</h2>
    1111
    1212<p>Deferreds are quite possibly the single most confusing topic that a
    13 newcomer to Twisted has to deal with. I am going to forgo the normal talk
    14 about what deferreds are, what they aren't, and why they're used in Twisted.
    15 Instead, I'm going show you the logic behind what they
    16 <strong>do</strong>.</p>
     13newcomer to Twisted has to deal with. I am going to forgo the normal
     14talk about what deferreds are, what they aren't, and why they're used
     15in Twisted.  Instead, I'm going show you the logic behind what
     16they <strong>do</strong>.</p>
    1717
    1818
    1919<p>A deferred allows you to encapsulate the logic that you'd normally use to
    callback 4 
    254254        got result: damage control successful!
    255255</pre>
    256256
    257 <p>Two things to note here. First, &quot;- A -&quot; was skipped, like we wanted it to,
    258 and the second thing is that after &quot;- A -&quot;, noDecision is called, because
    259 <strong>it is the next errback that exists in the chain</strong>. It returns a
    260 non-failure, so processing continues with the next callback at &quot;- B -&quot;, and
    261 the errback at the end of the chain is never called </p>
     257<p>Two things to note here. First, &quot;- A -&quot; was skipped, like
     258we wanted it to, and the second thing is that after &quot;- A -&quot;,
     259noDecision is called, because <strong>it is the next errback that
     260exists in the chain</strong>. It returns a non-failure, so processing
     261continues with the next callback at &quot;- B -&quot;, and the errback
     262at the end of the chain is never called </p>
    262263
    263264<h2>Hints, tips, common mistakes, and miscellaney</h2>
    264265
  • doc/core/howto/gendefer.xhtml

    diff --git a/doc/core/howto/gendefer.xhtml b/doc/core/howto/gendefer.xhtml
    index d391ea0..47da1ba 100644
    a b print "Adding the callback now." 
    120120d.addCallback(printNumber)
    121121</pre>
    122122
    123 <p>You will notice that despite creating a Deferred in the
    124 <code>largeFibonnaciNumber</code> function, these things happened:</p>
     123<p>You will notice that despite creating a Deferred in
     124the <code>largeFibonnaciNumber</code> function, these things
     125happened:</p>
    125126<ul>
    126127<li>the &quot;Total time taken for largeFibonnaciNumber call&quot; output
    127128shows that the function did not return immediately as asynchronous functions
    to know.</p> 
    286287
    287288<h3>Firing Deferreds more than once is impossible</h3>
    288289
    289 <p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or
    290 <code>Deferred.errback</code> once. The processing chain continues each time
    291 you add new callbacks to an already-called-back-to Deferred.</p>
     290<p>Deferreds are one-shot. You can only
     291call <code>Deferred.callback</code> or <code>Deferred.errback</code>
     292once. The processing chain continues each time you add new callbacks
     293to an already-called-back-to Deferred.</p>
    292294
    293295<h3>Synchronous callback execution</h3>
    294296
    295 <p>If a Deferred already has a result available, addCallback
    296 <strong>may</strong> call the callback synchronously: that is, immediately
    297 after it's been added.  In situations where callbacks modify state, it is
    298 might be desirable for the chain of processing to halt until all callbacks are
    299 added. For this, it is possible to <code>pause</code> and <code>unpause</code>
    300 a Deferred's processing chain while you are adding lots of callbacks.</p>
     297<p>If a Deferred already has a result available,
     298addCallback <strong>may</strong> call the callback synchronously: that
     299is, immediately after it's been added.  In situations where callbacks
     300modify state, it is might be desirable for the chain of processing to
     301halt until all callbacks are added. For this, it is possible
     302to <code>pause</code> and <code>unpause</code> a Deferred's processing
     303chain while you are adding lots of callbacks.</p>
    301304
    302305<p>Be careful when you use these methods! If you <code>pause</code> a
    303 Deferred, it is <em>your</em> responsibility to make sure that you unpause it.
    304 The function adding the callbacks must unpause a paused Deferred, it should
    305 <em>never</em> be the responsibility of the code that actually fires the
    306 callback chain by calling <code>callback</code> or <code>errback</code> as
    307 this would negate its usefulness!</p>
     306Deferred, it is <em>your</em> responsibility to make sure that you
     307unpause it.  The function adding the callbacks must unpause a paused
     308Deferred, it should <em>never</em> be the responsibility of the code
     309that actually fires the callback chain by
     310calling <code>callback</code> or <code>errback</code> as this would
     311negate its usefulness!</p>
    308312
    309313</body>
    310314</html>
  • doc/core/howto/process.xhtml

    diff --git a/doc/core/howto/process.xhtml b/doc/core/howto/process.xhtml
    index af4b2ec..8a67a32 100644
    a b reactor.spawnProcess(processProtocol, executable, args=[program, arg1, arg2], 
    8585
    8686</ul>
    8787
    88 <p><code>args</code> and <code>env</code> have empty default values, but
    89 many programs depend upon them to be set correctly. At the very least,
    90 <code>args[0]</code> should probably be the same as <code>executable</code>.
    91 If you just provide <code>os.environ</code> for <code>env</code>, the child
    92 program will inherit the environment from the current process, which is
    93 usually the civilized thing to do (unless you want to explicitly clean the
    94 environment as a security precaution). The default is to give an empty
    95 <code>env</code> to the child.</p>
     88<p><code>args</code> and <code>env</code> have empty default values,
     89but many programs depend upon them to be set correctly. At the very
     90least, <code>args[0]</code> should probably be the same
     91as <code>executable</code>.  If you just
     92provide <code>os.environ</code> for <code>env</code>, the child
     93program will inherit the environment from the current process, which
     94is usually the civilized thing to do (unless you want to explicitly
     95clean the environment as a security precaution). The default is to
     96give an empty <code>env</code> to the child.</p>
    9697
    9798<p><code>reactor.spawnProcess</code> returns an instance that
    9899implements <code base="twisted.internet.interfaces" class="API">
    reactor.run() 
    167168
    168169<h2>Things that can happen to your ProcessProtocol</h2>
    169170
    170 <p>These are the methods that you can usefully override in your subclass of
    171 <code>ProcessProtocol</code>:</p>
     171<p>These are the methods that you can usefully override in your
     172subclass of <code>ProcessProtocol</code>:</p>
    172173
    173174<ul>
    174175
    childFDs = { 0: "w", 1: "r", 2: "r" , 4: "w"} 
    380381
    381382<h3>ProcessProtocols with extra file descriptors</h3>
    382383
    383 <p>When you provide a <q>childFDs</q> dictionary with more than the normal
    384 three fds, you need addtional methods to access those pipes. These methods
    385 are more generalized than the <code>.outReceived</code> ones described above.
    386 In fact, those methods (<code>outReceived</code> and
    387 <code>errReceived</code>) are actually just wrappers left in for
    388 compatibility with older code, written before this generalized fd mapping was
    389 implemented. The new list of things that can happen to your ProcessProtocol
    390 is as follows:</p>
     384<p>When you provide a <q>childFDs</q> dictionary with more than the
     385normal three fds, you need addtional methods to access those
     386pipes. These methods are more generalized than
     387the <code>.outReceived</code> ones described above.  In fact, those
     388methods (<code>outReceived</code> and <code>errReceived</code>) are
     389actually just wrappers left in for compatibility with older code,
     390written before this generalized fd mapping was implemented. The new
     391list of things that can happen to your ProcessProtocol is as
     392follows:</p>
    391393
    392394<ul>
    393395