ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-18 02:39:51 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

CORDA-2423 document draining requirements in flow state machines (#4707)

Browse Source 
* CORDA-2423 document draining requirements in flow state machines

* Expand and move to warning block

* Add warning to hello-world-flow.rst
This commit is contained in:
Dominic Fox 2019-02-05 14:19:08 +00:00 committed by Mike Hearn
parent c667df9bec
commit 6cdd9f96b8
2 changed files with 20 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/source/flow-state-machines.rst
View File

@ -400,6 +400,17 @@ minutes, hours or even days in the case of a flow that needs human interaction!
special token that's recognised by the platform, and wired up to the right instance when the continuation is
loaded off disk again.
.. warning:: If a node has flows still in a suspended state, with flow continuations written to disk, it will not be
possible to upgrade that node to a new version of Corda or your app, because flows must be completely "drained"
before an upgrade can be performed, and must reach a finished state for draining to complete (see
:ref:`draining_the_node` for details). While there are mechanisms for "evolving" serialised data held
in the vault, there are no equivalent mechanisms for updating serialised checkpoint data. For this
reason it is not a good idea to design flows with the intention that they should remain in a suspended
state for a long period of time, as this will obstruct necessary upgrades to Corda itself. Any
long-running business process should therefore be structured as a series of discrete transactions,
written to the vault, rather than a single flow persisted over time through the flow checkpointing
mechanism.
``receive`` and ``sendAndReceive`` return a simple wrapper class, ``UntrustworthyData<T>``, which is
just a marker class that reminds us that the data came from a potentially malicious external source and may have been
tampered with or be unexpected in other ways. It doesn't add any functionality, but acts as a reminder to "scrub"

9
docs/source/hello-world-flow.rst
View File

@ -27,6 +27,15 @@ We also need the borrower to receive the transaction and record it for itself. A
to approve and sign IOU issuance transactions. We will be able to impose this requirement when we look at contracts in the
next tutorial.
.. warning:: The execution of a flow is distributed in space and time, as the flow crosses node boundaries and each
participant may have to wait for other participants to respond before it can complete its part of the
overall work. While a node is waiting, the state of its flow may be persistently recorded to disk as a
restorable checkpoint, enabling it to carry on where it left off when a counterparty responds. However,
before a node can be upgraded to a newer version of Corda, or of your Cordapp, all flows must have
completed, as there is no mechanism to upgrade a persisted flow checkpoint. It is therefore undesirable
to model a long-running business process as a single flow: it should rather be broken up into a series
of transactions, with flows used only to orchestrate the completion of each transaction.
Subflows
^^^^^^^^
Tasks like recording a transaction or sending a transaction to a counterparty are very common in Corda. Instead of