"debug" -- Debugging tools for Eventlet
***************************************

The debug module contains utilities and functions for better debugging
Eventlet-powered applications.

eventlet.debug.spew(trace_names=None, show_values=False)

   Install a trace hook which writes incredibly detailed logs about
   what code is being executed to stdout.

eventlet.debug.unspew()

   Remove the trace hook installed by spew.

eventlet.debug.format_hub_listeners()

   Returns a formatted string of the current listeners on the current
   hub.  This can be useful in determining what's going on in the
   event system, especially when used in conjunction with
   "hub_listener_stacks()".

eventlet.debug.format_hub_timers()

   Returns a formatted string of the current timers on the current
   hub.  This can be useful in determining what's going on in the
   event system, especially when used in conjunction with
   "hub_timer_stacks()".

eventlet.debug.hub_listener_stacks(state=False)

   Toggles whether or not the hub records the stack when clients
   register listeners on file descriptors.  This can be useful when
   trying to figure out what the hub is up to at any given moment.  To
   inspect the stacks of the current listeners, call
   "format_hub_listeners()" at critical junctures in the application
   logic.

eventlet.debug.hub_exceptions(state=True)

   Toggles whether the hub prints exceptions that are raised from its
   timers.  This can be useful to see how greenthreads are
   terminating.

eventlet.debug.tpool_exceptions(state=False)

   Toggles whether tpool itself prints exceptions that are raised from
   functions that are executed in it, in addition to raising them like
   it normally does.

eventlet.debug.hub_prevent_multiple_readers(state=True)

   Toggle prevention of multiple greenlets reading from a socket

   When multiple greenlets read from the same socket it is often hard
   to predict which greenlet will receive what data.  To achieve
   resource sharing consider using "eventlet.pools.Pool" instead.

   But if you really know what you are doing you can change the state
   to "False" to stop the hub from protecting against this mistake.

eventlet.debug.hub_timer_stacks(state=False)

   Toggles whether or not the hub records the stack when timers are
   set. To inspect the stacks of the current timers, call
   "format_hub_timers()" at critical junctures in the application
   logic.

eventlet.debug.hub_blocking_detection(state=False, resolution=1)

   Toggles whether Eventlet makes an effort to detect blocking
   behavior in an application.

   It does this by telling the kernel to raise a SIGALARM after a
   short timeout, and clearing the timeout every time the hub greenlet
   is resumed.  Therefore, any code that runs for a long time without
   yielding to the hub will get interrupted by the blocking detector
   (don't use it in production!).

   The *resolution* argument governs how long the SIGALARM timeout
   waits in seconds.  The implementation uses "signal.setitimer()" and
   can be specified as a floating-point value. The shorter the
   resolution, the greater the chance of false positives.
