Add a cachedproperty descriptor

It is pretty common that we create a property method that
checks if an instance variable is none, then creates it and
then sets the instance property (and then never gets called
to create it again, unless property is reset to none).

Apply this new property descriptor to a few places that are
redoing this same action over (don't repeat yourself principle
in action).

Change-Id: If6c20c5a2d145c51af3f3db56a4746eca8601253
Add an example which uses the run iteration functionality

Create an example which can run many engines at once using many
engines, each with its own iterator that can be used in a single
loop to cause that engine to progress to its next state.

Change-Id: I8c6ca19a752f4ced77fd86727f17ecad8c8e72c8
Use /taskflow/flush-test in the flush function

Instead of using /tmp use a taskflow specific
directory for the flush testing utility function
to make it possible to cleanup any leftover taskflow
test directories if/when a test crashes or fails without
cleaning itself up.

Change-Id: I4d06adf9b9fbf9ec70b511e763edb52a41293e39
Use futures wait() when possible

Instead of always using our custom future wait
functionality, only use that functionality if there
are green futures and in other cases just use the
future wait() function instead.

Change-Id: I1eadcf53eb4b5f47b9543965610bfe04fec52e70
Merge "Add a cachedproperty descriptor"
Merge "Use futures wait() when possible"
Merge "Add an example which uses the run iteration functionality"
Merge "Use /taskflow/flush-test in the flush function"
Complete the cachedproperty descriptor protocol

Refactor some parts of the cachedproperty property
descriptor (renaming attributes to the standard names
used in descriptor objects) and add on the __set__ and
__delete__ methods to comply with the full descriptor
protocol.

Change-Id: I1f1e8e301271c060d14acc3a77c094dabd120f16
Add tests for the misc.cachedproperty descriptor

Add a few tests that verify it is working as expected.

Change-Id: I6c062f84f7c2a6baf8fc9a697ebe2d715f82d332
Add engine state diagram

Add a nice visual representation of the states the action
engine yields back while executing (which are available from
its run_iter method) and give a brief overview of what these
states mean and how they are used (in diagram and in text).

Change-Id: Idc6abc83e0ed7510c0e4c58b7fcfc26cce3e98a2
Fix error string interpolation

The values were not correctly being interpolated
into the value error that is thrown when merging
graphs together and they have overlapping nodes.

Fix this by correctly interpolating and expanding
the messaging/reason why we do not support
overlapping graphs.

Change-Id: Iff29f793c7dfd6b39a4936c7f4f31fd660262ca6
Merge "Add engine state diagram"
Add a example which uses the run_iter function in a for loop

The run iteration capability can be used to iterate over the
engines activity and do various other activities in-between
the engine state iteration; this example shows a primitive
use of this to output the state counter and the transition
itself.

Change-Id: I63ac343566a4a090a20a84c626ddea3651033926
Add kwarg check_pending argument to fake lock

To ensure we retain the same API for the fake lock
class make sure we have the is_writer function take
in the same kwarg as the base class.

Change-Id: Id39deeb8cc944dad05a36bd48993f11f2f11118e
Add source of engine-state sequence diagram

To allow others to recreate this sequence diagram
include the source to that diagram so that it can
be regenerated (if needed) in the future.

Change-Id: I68dfea274e679e09a9d5e34af28d05d766856686
Regenerate engine-state sequence diagram

There was a spelling mistake in the image, fix
it and regenerate it so that this spelling mistake
no longer exists.

Change-Id: I9090916fe133d979af25c5828f3006c46d59aaeb
Standardize on the same capitalization pattern

Inside of mixing capitalization in title sections just
be consistent and capitalize the first word and then
have the rest of the title be lower cased.

Change-Id: I1170ab2ee3d5d3801ec4022d1c81d8173cbdd8df
Rework the overview of the notification mechanism

Clean up the introduction where the notification mechanism
is defined so that it becomes more clear what its usage is
and what the attributes of an engine are that provide these
capabilities.

Change-Id: I4eeb9029b17d562111371c6f5155570b7a31859c
Add doc link to examples

To make it easy to find where the examples are
located at a section of the developer docs that
links to the source tree examples directory.

Change-Id: Ie2222e7cb221764749353e0d05fa1df44c2db514