From 3a7e925ec34700d8832ef2ff9028b970a2886216 Mon Sep 17 00:00:00 2001
From: James Clark <jjc@jclark.com>
Date: Tue, 15 Dec 2020 08:50:19 +0700
Subject: [PATCH] Explain how transactions work with services/clients

Part of #267.
---
 lang/spec.html | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/lang/spec.html b/lang/spec.html
index 238cad0f..e973cf44 100644
--- a/lang/spec.html
+++ b/lang/spec.html
@@ -8594,11 +8594,38 @@ <h3 id="transactions">Transactions</h3>
 the current transaction branch for that strand.
 </p>
 <p>
+Static checking is based on the idea of a transactional scope: this is a lexical
+region of the program where it is known that at runtime the strand executing the
+region will always be in transactional mode. A function with the
+<code>transactional</code> qualifier can only be called in a transactional
+scope; this includes function calls using <code>start</code>.
+</p>
+<p>
 A running instance of a Ballerina program includes a transaction manager. This
 may run in the same process as the Ballerina program or in a separate process.
 It should not be connected over an unreliable network.
 </p>
 <p>
+When a global transaction involves multiple Ballerina programs, there must be a
+network protocol that allows that transaction managers in each program to
+communicate. The protocol must also allow a remote method or resource method on
+a service object to be informed of the global transaction, if any, to which it
+belongs. When a listener object determines that a remote method or resource
+method of a service object is to be a part of a global transaction manager, then
+it will create a new transaction branch, join it to the global transaction and
+push that on the transaction stack for the strand on which the method is called;
+if the method is declared as <code>transactional</code>, the listener will not
+call the method unless it can do this. Similarly, the protocol must allow a
+remote method on a client object that is called in transaction mode to send
+information about the global transaction of which it is part; if the method is
+declared as <code>transactional</code>, then as usual the method can only be
+called in transaction mode; it also implies that the client object
+implementation is transaction-aware, and that the recipient of the message sent
+by the remote method must join the global transaction. A global transaction can
+combine Ballerina programs with programs written in other programming languages
+provided they agree on this network protocol.
+</p>
+<p>
 A strand in transaction mode can register commit or rollback handlers with the
 transaction manager for the current transaction branch, which are functions
 which will be called by the transaction manager when the decision has been made
@@ -8612,17 +8639,10 @@ <h3 id="transactions">Transactions</h3>
 programmer to do this using commit or rollback handlers.
 </p>
 <p>
-Static checking is based on the idea of a transactional scope: this is a lexical
-region of the program where it is known that at runtime the strand executing the
-region will always be in transactional mode. A function with the
-<code>transactional</code> qualifier can only be called in a transactional
-scope; this includes function calls using <code>start</code>.
-</p>
-<p>
 When a new strand is created by a named-worker-decl that includes a
 <code>transactional</code> qualifier or by using <code>start</code> to call a
 function with a <code>transactional</code> qualifier, a new transaction branch
-will be created and joined to the current transaction; this transaction branch
+will be created and joined to the global transaction; this transaction branch
 will be pushed onto transaction stack for the newly created strand.
 </p>
 <p>