reactor.callWhenRunning is not in the Using Processes document

[hagna]

The way to get rid of a race condition where spawnprocess is called before the
signal handler is installed is to use reactor.callWhenRunning(spawnprocess ...).
 The examples in "Using Processes" don't mention the race condition or the
solution.  

Here is an example that doesn't use callWhenRunning.  It would work fine if it
was using callWhenRunning.

[thijs]

Shall I create a patch that adds this to the core docs? Can anyone review this example?

[exarkun]

This example is rather complex. A simpler example would be more like this (untested):

from twisted.internet.utils import getProcessOutput
from twisted.internet import reactor

d = getProcessOutput('/bin/echo', ['/bin/echo', 'foo'])
def cbOutput(output):
    print output
    reactor.stop()
d.addCallback(cbOutput)
reactor.run()

This would better be written (for the time being) as

from twisted.internet.utils import getProcessOutput
from twisted.internet import reactor

def getOutput():
    d = getProcessOutput('/bin/echo', ['/bin/echo', 'foo'])
    def cbOutput(output):
        print output
        reactor.stop()
    d.addCallback(cbOutput)
reactor.callWhenRunning(getOutput)
reactor.run()

[thijs]

(In [24448]) Branching to 'callwhenrunning-doc-1246'

[thijs]

Replying to exarkun:

This example is rather complex. A simpler example would be more like this (untested): ...

I added your example in a branch with the terse description hagna offered. Let me know how it looks and fits.

[exarkun]

spawnprocess in the prose should be capitalized properly and would probably benefit from being an API link. The reference to reactor.callWhenRunning following it could be an API link too.

I'd suggest dropping the mention of a "signal handler" and just talk about how calling reactor.spawnProcess before calling reactor.run can lead to a race where process exit isn't noticed (and a warning emitted). Then it becomes more clear how using reactor.callWhenRunning helps. This should also help make the statement "The way to get rid of a race condition..." more clear, because the actual race condition will have been defined in the document, which it currently isn't.

Also, my example contained a bug - getProcessOutput does not take argv[0] as part of the argument list, but I included it because I always forget about that inconsistency.

Thanks!

[thijs]

Replying to exarkun:

spawnprocess in the prose should be capitalized properly and would probably benefit from being an API link. The reference to reactor.callWhenRunning following it could be an API link too. I'd suggest dropping the mention of a "signal handler" and just talk about how calling reactor.spawnProcess before calling reactor.run can lead to a race where process exit isn't noticed (and a warning emitted). Then it becomes more clear how using reactor.callWhenRunning helps. This should also help make the statement "The way to get rid of a race condition..." more clear, because the actual race condition will have been defined in the document, which it currently isn't.

Rewrote it in r24642, putting it up for review.

Also, my example contained a bug - getProcessOutput does not take argv[0] as part of the argument list, but I included it because I always forget about that inconsistency.

What does this mean, something like this?

- d = getProcessOutput('/bin/echo', ['/bin/echo', 'foo'])
+ d = getProcessOutput('/bin/echo')

[exarkun]

It means d = getProcessOutput('/bin/echo', ['foo'])

[thijs]

Replying to exarkun:

It means d = getProcessOutput('/bin/echo', ['foo'])

Fixed in r24645

[exarkun]

Looks good, please merge.

[thijs]

(In [24652]) Merge callwhenrunning-doc-1246: add a new sample for reactor.callWhenRunning in the Using Processes document.

Author: hagna, exarkun, thijs Reviewer: exarkun Fixes: #1246