Ticket #4568: core-lowlevel.xhtml.patch

File core-lowlevel.xhtml.patch, 17.1 KB (added by jdb, 4 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