Rework pieces of the task callback capability

Unifies the bind, unbind, autobind parameters.

Also to make it easier to introspect what are a tasks associated
callbacks and events are provide a listeners_iter() method that
can be used to introspect the registered (event, callbacks) pairs that
are registered with a task.

Also adds more useful docstrings to the various callback associated
binding, unbinding functions to make it more understandable how they
are used and what they are provided.

Also makes the currently only default provided event 'update_progress'
a constant that can be referenced from the task module, which allows others
to easily find it and use it.

Change-Id: I14181a150b74fbd97f6ea976723f37c0ba4cec36
Ensure that failures can be pickled

When a failure happens in a subprocess it needs to be
pickleable (and not contain a traceback, since those can
not be pickled) when being sent across the process boundary
so that the receiving process can read it and unpickle
the corresponding object.

Part of blueprint process-executor

Change-Id: I2f26faa4e02da6acf4f0840239d0b17143de8d76
Allow stopwatches to be restarted

It is quite useful to allow a stopwatch to be reset
or restarted in a single operation, instead of having
to handle this logic outside of the stopwatch object,
which is error-prone and unnecessary to require users
to reinvent.

Part of blueprint process-executor

Change-Id: Ie0304a4f1d5f6bf0460e9a134762d1403da56375
Have tasks be able to provide copy() methods

When a engine needs to copy a task and possibly
adjust its listeners to execute it elsewhere it
needs to be able to clone that object and have
the clone retain different properties than the
initial object; so in order to support this at
a top-level we require a new copy() method which
a task can override (or it can just use the default
implementation if it chooses to).

Part of blueprint process-executor

Change-Id: Ib29a0afdc01973eb94d41af18a9b04601cd2f152
Stop returning atoms from execute/revert methods

It is not needed to return the atom that was executed from the
futures result() method, since we can just as easily set an
attribute on the future and reference it from there when using
it later. This is also required for a process based executor since
it is not typically possible to send back a raw task object (and
is not desireable to require this); even if it was possible the
task would be pickled and unpickled multiple times so when this
happens it can not be guaranteed to even be the same object (in
fact it is not).

Part of blueprint process-executor

Change-Id: I4a05ea5dcdef97218312e3a88ed4a1dfdf1b1edf
Allow all deprecation helpers to take a stacklevel

To make the deprecation helpers more uniform in what
arguments/keyword arguments they take allow them all
to take a stacklevel keyword argument (which by default
is set to a good value that works).

This allows those users of this helper to override the
stacklevel in a uniform manner (if they so need to).

Change-Id: Icbfc115aa2aea4a5c01b99dcfa2a5c4e4785c458
Use an appropriate ``extract_traceback`` limit

When looking for where this modules ``run/load`` ends and
the user code begins we only need to search back at most
three levels to find this information; so to avoid getting
many more frames (especially when they won't be used) then
we need to just apply a sensible limit on the levels we get.

Change-Id: I9186e8844c92697b7e3f850328b6b39afba0150d
Use condition variables using 'with'

Instead of doing [acquire, try, finally, release]
just use the condition variable as a context manager
to achieve the same effect with less code and with
less verbosity.

Change-Id: I0a3bb80a932a3dc6623ba2378afa0341e9e06e5a
Add appropriate links into README.rst

The oslo repositories are standardizing on a common
set of links to include in README.rst (which the
release note script will also use); so therefore we
should add our own set to match those other projects.

Change-Id: I58cbcd9b36fd0432b59e9eec3ad5ab54a1fede3a
Merge "Add appropriate links into README.rst"
Merge "Rework pieces of the task callback capability"
Merge "Ensure that failures can be pickled"
Merge "Allow stopwatches to be restarted"
Merge "Have tasks be able to provide copy() methods"
Merge "Use an appropriate ``extract_traceback`` limit"
Merge "Stop returning atoms from execute/revert methods"
Merge "Allow all deprecation helpers to take a stacklevel"
Remove rtype from task clone() doc

The sphinx docs don't seem to show this parameter
correctly when building the html docs so instead of
showing it just remove since the return type should
be pretty obvious due to the surronding text.

Change-Id: Id27c23d79d7fdbcd677ed959d9d817c796a0828c
Just assign a empty collection instead of copy/clear

Instead of copying the '_events_listeners' then clear
them to get a clean copy just set the copies '_events_listeners'
to a new collection in the first place.

Change-Id: I17d4f02241c90a49fc4334cfd1f2fffd03d58927
Merge "Just assign a empty collection instead of copy/clear"