From 212ff19f5d9950f680be3b52cb53994b2df734d4 Mon Sep 17 00:00:00 2001
From: Anders Svensson <anders@erlang.org>
Date: Fri, 15 Feb 2019 15:02:09 +0100
Subject: Document acknowledgements in transport interface

This is the {diameter, ack} message from a transport process to its
parent that requests that every Diameter request passed to the parent be
matched by a incoming send message, the atom false replacing a message()
in the case that the request is unanswered, allowing the transport to
keep track of the number of outstanding requests.

These were added in commit ca09cf7b, and are used to implement the
message_cb config in diameter_tcp/sctp, documented in commit cefcaa5c.

This commit documents the interface, to make it available to other
transport implementations.
---
 lib/diameter/doc/src/diameter_transport.xml | 31 ++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

(limited to 'lib/diameter')

diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 294e8a8864..099c600bf3 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -14,7 +14,8 @@
 <erlref>
 <header>
 <copyright>
-<year>2011</year><year>2016</year>
+<year>2011</year>
+<year>2019</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 <legalnotice>
@@ -174,10 +175,13 @@ its parent.</p>
 
 <taglist>
 
-<tag><c>{diameter, {send, &message;}}</c></tag>
+<tag><c>{diameter, {send, &message; | false}}</c></tag>
 <item>
 <p>
-An outbound Diameter message.</p>
+An outbound Diameter message.
+The atom <c>false</c> can only be received when request
+acknowledgements have been requests: see the <c>ack</c> message
+below.</p>
 </item>
 
 <tag><c>{diameter, {close, Pid}}</c></tag>
@@ -246,6 +250,27 @@ A <c>LocalAddr</c> list has the same semantics as one returned from
 &start;.</p>
 </item>
 
+<tag><c>{diameter, ack}</c></tag>
+<item>
+<p>
+Request acknowledgements of unanswered requests.
+A transport process should send this once before passing incoming
+Diameter messages into diameter.
+As a result, every Diameter request passed into diameter with a
+<c>recv</c> message (below) will be answered with a
+<c>send</c> message (above), either a &message; for the transport
+process to send or the atom <c>false</c> if the request has been
+discarded or otherwise not answered.</p>
+
+<p>
+This is to allow a transport process to keep count of the number
+of incoming request messages that have not yet been answered or
+discarded, to allow it to regulate the amount of incoming traffic.
+Both diameter_tcp and diameter_sctp request acknowledgements when a
+<c>message_cb</c> is configured, turning send/recv message into
+callbacks that can be used to regulate traffic.</p>
+</item>
+
 <tag><c>{diameter, {recv, &message;}}</c></tag>
 <item>
 <p>
-- 
cgit v1.2.3