Modified interfaces so that they return a cancellable future.  I did
this as the first part of addressing a deadlock when backing out.
Next commits will explain more.
Minor documentation additions.