Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/agprojects/python-eventlib

Networking library for SIP SIMPLE Client SDK
https://github.com/agprojects/python-eventlib

Last synced: 11 days ago
JSON representation

Networking library for SIP SIMPLE Client SDK

Awesome Lists containing this project

README 

        
--work in progress--



Introduction

------------

Twisted provides solid foundation for asynchronous programming in Python.

Eventlet makes asynchronous programming look like synchronous, thus

achieving higher signal-to-noise ratio than traditional twisted programs have.



Eventlet on top of twisted provides:

 * [stable twisted]

 * [usable and readable synchronous style]

 * existing twisted code can be used without any changes

 * existing blocking code can be used after trivial changes applied



Eventlet features:



 * utilities for spawning and controlling greenlet execution:

   api.spawn, api.kill, proc module

 * utilities for communicating between greenlets:

   coros.event, coros.queue, proc module

 * standard Python modules that won't block the reactor:

   eventlet.green package

 * utilities specific to twisted hub:

   eventlet.twistedutil package



Getting started with eventlet on twisted

----------------------------------------



This section will only mention stuff that may be useful but it

won't explain in details how to use it. For that, refer to the

docstrings of the modules and the examples.



There are 2 ways of using twisted with eventlet, one that is

familiar to twisted developers and another that is familiar

to eventlet developers:



 1. explicitly start the main loop in the main greenlet;

 2. implicitly start the main loop in a dedicated greenlet.



To enable (1), add this line at the top of your program:

from eventlet.twistedutil import join_reactor

then start the reactor as you would do in a regular twisted application.



For (2) just make sure that you have reactor installed before using

any of eventlet functions. Otherwise a non-twisted hub will be selected

and twisted code won't work.



Most of examples/twisted_* use twisted style with the exception of

twisted_client.py and twisted_srvconnector.py. All of the non-twisted

examples in examples directory use eventlet-style (they work with any

of eventlet's hubs, not just twisted-based).



Eventlet implements "blocking" operations by switching to the main loop

greenlet, thus it's impossible to call a blocking function when you are

already in the main loop. Therefore one must be cautious in a twisted

callback, calling only a non-blocking subset of eventlet API here. The

following functions won't unschedule the current greenlet and are safe

to call from anywhere:



1. Greenlet creation functions: api.spawn, proc.spawn,

   twistedutil.deferToGreenThread and others based on api.spawn.



2. send(), send_exception(), poll(), ready() methods of coros.event

   and _unbounded_ coros.queue.



3. wait(timeout=0) is identical to poll(). Currently only Proc.wait

   supports timeout parameter.



4. Proc.link/link_value/link_exception



Other classes that use these names should follow the convention.



For an example on how to take advantage of eventlet in a twisted

application using deferToGreenThread see examples/twisted_http_proxy.py



Although eventlet provides eventlet.green.socket module that implements

interface of the standard Python socket, there's also a way to use twisted's

network code in a synchronous fashion via GreenTransport class.

A GreenTransport interface is reminiscent of socket but it's not a drop-in

replacement. It combines features of TCPTransport and Protocol in a single

object:



 * all of transport methods (like getPeer()) are available directly on

   a GreenTransport instance; in addition, underlying transport object

   is available via 'transport' attribute;

 * write method is overriden: it may block if transport write buffer is full;

 * read() and recv() methods are provided to retrieve the data from protocol

   synchronously.



To make a GreenTransport instance use twistedutil.protocol.GreenClientCreator

(usage is similar to that of twisted.internet.protocol.ClientCreator)



For an example on how to get a connected GreenTransport instance,

see twisted_client.py, twisted_srvconnect.py or twisted_portforward.py.

For an example on how to use GreenTransport for incoming connections,

see twisted_server.py, twisted_portforward.py.



also

* twistedutil.block_on - wait for a deferred to fire

  block_on(reactor.callInThread(func, args))

* twistedutil.protocol.basic.LineOnlyReceiverTransport - a green transport

  variant built on top of LineOnlyReceiver protocol. Demonstrates how

  to convert a protocol to a synchronous mode.



Coroutines

----------



To understand how eventlet works, one has to understand how to use greenlet:

http://codespeak.net/py/dist/greenlet.html



Essential points



* There always exists MAIN greenlet

* Every greenlet except MAIN has a parent. MAIN therefore could be detected as g.parent is None

* When greenlet is finished it's return value is propagated to the parent (i.e. switch() call

  in the parent greenlet returns it)

* When an exception leaves a greelen, it's propagated to the parent (i.e. switch() in the parent

  re-raises it) unless it's a subclass of GreenletExit, which is returned as a value.

* parent can be reassigned (by simply setting 'parent' attribute). A cycle would be detected and

  rejected with ValueError



Note, that there's no scheduler of any sort; if a coroutine wants to be

scheduled again it must take care of it itself. As an application developer,

however, you don't need to worry about it as that's what eventlet does behind

the scenes. The cost of that is that you should not use greenlet's switch() and

throw() methods, they will likely leave the current greenlet unscheduled

forever. Eventlet also takes advantage of greenlet's `parent' attribute,

so you should not meddle with it either.



How does eventlet work

----------------------



Twisted's reactor and eventlet's hub are very similar in what they do.

Both continuously preform polling on the list of registered descriptors

and each time a specific event is fired, the associated callback function

is called. In addition, both maintain a list of scheduled calls.



Polling is performed by the main loop - a function that both reactor and hub have.

When twisted calls user's callback it's expected to return almost immediately,

without any blocking I/O calls. Deferreds help there.



Eventlet runs the main loop in a dedicated greenlet (MAIN_LOOP). It is the same

greenlet as MAIN if you use join_reactor. Otherwise it's a separate greenlet

started implicitly. The execution is organized in a such way that the switching

always involves MAIN_LOOP. All of functions in eventlet that appear "blocking"

use the following algorithm:



1. register a callback that switches back to the current greenlet when

   an event of interest happens

2. switch to the MAIN_LOOP



For example, here's what eventlet's socket recv() does:



= blocking operation RECV on socket d =



user's greenlet (USER)             main loop's greenlet (MAIN_LOOP)

      |

(inside d.recv() call)

      |

add_descriptor(d, RECV)

      |

data=MAIN_LOOP.switch() ---------> poll for events

  ^---------------------\               |

                        |              ... ---------------------------> may execute other greenlets here

                        |               |

                        |          event RECV on descriptor d?

                        |               |

                        |          d.remove_descriptor(d, RECV)

                        |               |

                        |          data = d.recv() # calling blocking op that will return immediately

                        |               |

                        \--------- USER.switch(data) # argument data here becomes return value in user's switch

  return data