"backdoor" -- Python interactive interpreter within a running process
*********************************************************************

The backdoor module is convenient for inspecting the state of a long-
running process.  It supplies the normal Python interactive
interpreter in a way that does not block the normal operation of the
application.  This can be useful for debugging, performance tuning, or
simply learning about how things behave in situ.

In the application, spawn a greenthread running backdoor_server on a
listening socket:

   eventlet.spawn(backdoor.backdoor_server, eventlet.listen(('localhost', 3000)))

When this is running, the backdoor is accessible via telnet to the
specified port.

   $ telnet localhost 3000
   Python 2.6.2 (r262:71600, Apr 16 2009, 09:17:39)
   [GCC 4.0.1 (Apple Computer, Inc. build 5250)] on darwin
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import myapp
   >>> dir(myapp)
   ['__all__', '__doc__', '__name__', 'myfunc']
   >>>

The backdoor cooperatively yields to the rest of the application
between commands, so on a running server continuously serving
requests, you can observe the internal state changing between
interpreter commands.

class eventlet.backdoor.SocketConsole(desc, hostport, locals)

   switch(*args, **kwargs)

      Switch execution to this greenlet.

      If this greenlet has never been run, then this greenlet will be
      switched to using the body of self.run(>>*<<args, >>**<<kwargs).

      If the greenlet is active (has been run, but was switch()'ed out
      before leaving its run function), then this greenlet will be
      resumed and the return value to its switch call will be None if
      no arguments are given, the given argument if one argument is
      given, or the args tuple and keyword args dict if multiple
      arguments are given.

      If the greenlet is dead, or is the current greenlet then this
      function will simply return the arguments using the same rules
      as above.

eventlet.backdoor.backdoor(conn_info, locals=None)

   Sets up an interactive console on a socket with a single connected
   client.  This does not block the caller, as it spawns a new
   greenlet to handle the console.  This is meant to be called from
   within an accept loop (such as backdoor_server).

eventlet.backdoor.backdoor_server(sock, locals=None)

   Blocking function that runs a backdoor server on the socket *sock*,
   accepting connections and running backdoor consoles for each client
   that connects.

   The *locals* argument is a dictionary that will be included in the
   locals() of the interpreters.  It can be convenient to stick
   important application variables in here.
