connection to be returned might get inadvertently cleaned out during
the "cleanup" process.  Patch courtesy jd23.

- add huge warning regarding how use_threadlocal probably not what you want

:class:`.RootTransaction` or :class:`.TwoPhaseTransaction`
with its immediate :class:`._ConnectionFairy` as a "reset handler"
for the span of that transaction, which takes over the task
of calling commit() or rollback() for the "reset on return" behavior
of :class:`.Pool` if the transaction was not otherwise completed.
This resolves the issue that a picky transaction
like that of MySQL two-phase will be
properly closed out when the connection is closed without an
explicit rollback or commit (e.g. no longer raises "XAER_RMFAIL"
in this case - note this only shows up in logging as the exception
is not propagated within pool reset).
This issue would arise e.g. when using an orm
:class:`.Session` with ``twophase`` set, and then
:meth:`.Session.close` is called without an explicit rollback or
commit.   The change also has the effect that you will now see
an explicit "ROLLBACK" in the logs when using a :class:`.Session`
object in non-autocommit mode regardless of how that session was
discarded.  Thanks to Jeff Dairiki and Laurence Rowe for isolating
the issue here. [ticket:2907]

events including auto-invalidation, which is useful both for tests here as well as
detecting failure conditions within the "reset" or "close" cases.
- rename the argument for PoolEvents.reset() to dbapi_connection and connection_record
to be consistent with everything else.
- add new documentation sections on invalidation, including auto-invalidation
and the invalidation process within the pool.
- add _ConnectionFairy and _ConnectionRecord to the pool documentation.  Establish
docs for common _ConnectionFairy/_ConnectionRecord methods and accessors and
have PoolEvents docs refer to _ConnectionRecord,
since it is passed to all events.  Rename a few _ConnectionFairy methods that are actually
private to pool such as _checkout(), _checkin() and _checkout_existing(); there should not
be any external code calling these

attempts when an existing connection attempt is blocking.  Previously,
the production of new connections was serialized within the block
that monitored overflow; the overflow counter is now altered within
it's own critical section outside of the connection process itself.
[ticket:2880]

- rework the event system so that event modules load after their
targets, dependencies are reversed
- create an improved strategy lookup system for the ORM
- rework the ORM to have very few import cycles
- move out "importlater" to just util.dependency
- other tricks to cross-populate modules in as clear a way as possible

ideas in general:
  - pypy2.1 w/ sqlite3 is the first DBAPI we're seeing returning
    unicode in cursor.description without being py3k.  add a new on-connect
    check for this, if we get back a u"", just don't do description decoding,
    should be OK for now.
  - the set tests in test_collection were assuming the two sets would be ordered
    the same when it tested pop(), can't really assume that.
  - test_serializer gets worse and worse, pickle is just not really viable here,
    ding out pypy
  - pypy2.1b2 seems to allow cursor.lastrowid to work (or we changed something?)
  - pool._threadconns.current() is a weakref, it can be None
  - another one of those logging.handlers imports