[Twisted-Python] CONNECTION_LOST not an integer (docstring error?)

[Jean-Paul Calderone]

On Wed, 1 Oct 2008 15:24:05 -0600, Michael McNeil Forbes <mforbes at physics.ubc.ca> wrote:
>On Oct 1, 2008, at 12:04 PM, Jean-Paul Calderone wrote:
>>On Wed, 1 Oct 2008 12:00:29 -0600, Michael McNeil Forbes 
>><mforbes at physics.ubc.ca> wrote:
>>>Several places in the documentation refer to the method  writeSomeData () 
>>>returning a negative integer if the connection is  lost.  (In  particular 
>>>/api/  twisted.internet.abstract.FileDescriptor.html#writeSomeData.)
>>>
>>>However, twisted.internet.main.CONNECTION_LOST is often returned   which 
>>>is not an integer.
>...
>>Hardly anyone actually needs `writeSomeData`.  It's mostly an 
>>implementation
>>detail of a certain group of reactors.
>
>I have opened a ticket.  A question then that is sure to expose my 
>ignorance of twisted...

Thanks. :)

>Why does writeSomeData not simply raise CONNECTION_LOST as an  exception? 
>Checking return values is quite un-pythonic.  Is there a  deep reason for 
>this?

The reason is probably that whoever wrote it thought that raising an
exception would be enough slower than returning a special value that
it would be worth doing something slightly unusual.  Compared to
returning a value, raising an exception is expensive in CPython, but
I doubt there is any surviving benchmark which demonstrates that it
makes a difference here.

However, it's a very low-level API and since it isn't intended to be
used by application code, it doesn't seem like a very high priority
to make it less confusing.

>
>P.S. I came across this because I was trying to use twisted running  in a 
>thread to write data resulting from a long computation that I  have not yet 
>turned into a producer.  The more conventional "write"  method was failing 
>if the socket backed up, and provided no simple  way of determining if data 
>was being dropped.  My solution was to  used writeSomeData, and then have 
>the computation decide to throw out  some of the data if it is being 
>produced too rapidly, but I need to  know how much has been sent so I can 
>decide what to throw away...
>

This seems more interesting than the main point of your email. :) You
should probably just do the work to turn the computation into a producer.
This because:

  * writeSomeData is low level and crufty, as you've discovered
  * Not all reactors have this API, so your program will break based on
    the reactor selected to run it
  * producers give you all the same information

Since you mentioned threads, I'll also point out that Twisted APIs are not
safe to use from non-reactor threads without reactor.callFromThread.  If
you aren't using callFromThread, that would explain bad behavior from the
write method.

Jean-Paul