From cefcaa5c1a3f49e2c8e277962326dfdb53ce6a4f Mon Sep 17 00:00:00 2001
From: Anders Svensson <anders@erlang.org>
Date: Tue, 19 Sep 2017 18:14:04 +0200
Subject: Document new(ish) options in diameter_tcp/sctp

See commits d3829525 (unordered), c591056b (packet), eadf4efc (sender),
636a7199 (tcp message_cb), 373cd07c (sctp message_cb)
---
 lib/diameter/doc/src/diameter_sctp.xml | 62 ++++++++++++++++++++++++----------
 lib/diameter/doc/src/diameter_tcp.xml  | 45 ++++++++++++++++++++++--
 2 files changed, 88 insertions(+), 19 deletions(-)

(limited to 'lib')

diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index 9b6d629f79..f00f3b2712 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY man_tcp_sender
+  '<seealso marker="diameter_tcp#sender">diameter_tcp(3)</seealso>'>
   <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'>
   <!ENTITY gen_sctp_open1
   '<seealso marker="kernel:gen_sctp#open-1">gen_sctp:open/1</seealso>'>
@@ -16,7 +18,7 @@
 <header>
 <copyright>
 <year>2011</year>
-<year>2016</year>
+<year>2017</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 <legalnotice>
@@ -78,7 +80,11 @@ and implements the behaviour documented in
 <v>Reason = term()</v>
 <v>OwnOpt = {raddr, &ip_address;}
           | {rport, integer()}
-          | {accept, Match}</v>
+          | {accept, Match}
+          | {unordered, boolean() | pos_integer()}
+          | {packet, boolean() | raw}
+          | {message_cb, &mod_eval;}
+          | {sender, boolean()}</v>
 <v>SctpOpt = term()</v>
 <v>Match = &ip_address; | string() | [Match]</v>
 </type>
@@ -105,6 +111,41 @@ Multiple <c>accept</c> options can be specified.
 A string-valued <c>Match</c> that does not parse as an address is
 interpreted as a regular expression.</p>
 
+<p>
+Option <c>unordered</c> specifies whether or not to use unordered
+delivery, integer <c>N</c> being equivalent to <c>N =&lt; OS</c>,
+where <c>OS</c> is the number of outbound streams negotiated on the
+association in question.
+Regardless of configuration, sending is ordered on stream 0
+until reception of a second incoming message, to ensure that a peer
+receives capabilities exchange messages before any other.
+Defaults to <c>false</c>.</p>
+
+<p>
+Option <c>packet</c> determines how/if an incoming message is
+packaged into a diameter_packet record.
+If <c>false</c> then messages are received as binary().
+If <c>true</c> then as a record with the binary() message in the
+<c>bin</c> field and a <c>{stream, Id}</c> tuple in the
+<c>transport_data</c> field, where <c>Id</c> is the identifier of the
+inbound stream the message was received on.
+If <c>raw</c> then as a record with the received ancillary
+sctp_sndrcvinfo record in the <c>transport_data</c> field.
+Defaults to <c>true</c>.</p>
+
+<p>
+Options <c>message_cb</c> and <c>sender</c> have semantics identical
+to those documented in &man_tcp_sender;, but with the message argument
+to a <c>recv</c> callback being as directed by the <c>packet</c>
+option.</p>
+
+<p>
+An <c>{outstream, Id}</c> tuple in the <c>transport_data</c> field of
+a outgoing diameter_packet record sets the outbound stream on which
+the message is sent, modulo the negotiated number of outbound streams.
+Any other value causes successive such sends to cycle though all
+outbound streams.</p>
+
 <p>
 Remaining options are any accepted by &gen_sctp_open1;, with the exception
 of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
@@ -122,29 +163,16 @@ connecting transport.</p>
 
 <warning>
 <p>
-An insufficiently large receive buffer may result in a peer having to
+An small receive buffer may result in a peer having to
 resend incoming messages: set the &inet; option <c>recbuf</c> to increase
 the buffer size.</p>
 
 <p>
-An insufficiently large send buffer may result in outgoing messages
+An small send buffer may result in outgoing messages
 being discarded: set the &inet; option <c>sndbuf</c> to increase
 the buffer size.</p>
 </warning>
 
-<p>
-The <c>transport_data</c> field of record <c>diameter_packet</c>
-is used to communicate the stream on which an inbound message
-has been received, or on which an outbound message should be sent.
-The value will be of the form <c>{stream, Id}</c> for an inbound
-message passed to a &app_handle_request; or &app_handle_answer;
-callback.
-For an outbound message, <c>{outstream, Id}</c> in the return value of
-&app_handle_request; or &app_prepare_retransmit; sets the outbound
-stream, the stream id being interpreted modulo the number of outbound
-streams.
-Any other value, or not setting a value, causes successive such sends
-to cycle though all outbound streams.</p>
 </desc>
 </func>
 
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index 6ca280c52b..4644a05331 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -27,7 +27,8 @@
 <erlref>
 <header>
 <copyright>
-<year>2011</year><year>2016</year>
+<year>2011</year>
+<year>2017</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 <legalnotice>
@@ -99,7 +100,9 @@ before configuring TLS capability on diameter transports.</p>
           | {rport, integer()}
           | {accept, Match}
           | {port, integer()}
-          | {fragment_timer, infinity | 0..16#FFFFFFFF}</v>
+          | {fragment_timer, infinity | 0..16#FFFFFFFF}
+          | {message_cb, &mod_eval;}
+          | {sender, boolean()}</v>
 <v>SslOpt = {ssl_options, true | list()}</v>
 <v>TcpOpt = term()</v>
 <v>Match = &ip_address; | string() | [Match]</v>
@@ -140,6 +143,44 @@ such a message is received over the transport interface after
 two successive timeouts without the reception of additional bytes.
 Defaults to 1000.</p>
 
+<marker id="sender"/>
+<p>
+Option <c>sender</c> specifies whether or not to use a dedicated
+process for sending outgoing messages, which avoids the possibility of
+send blocking reception.
+Defaults to <c>false</c>.
+If set to <c>true</c> then a <c>message_cb</c> that avoids the
+possibility of messages being queued in the sender process without
+bound should be configured.</p>
+
+<p>
+Option <c>message_cb</c> specifies a callback that is invoked on
+incoming and outgoing messages, that can be used to implement
+flow control.
+It is applied to two arguments: an atom indicating the
+reason for the callback (<c>send</c>, <c>recv</c>, or <c>ack</c> after
+a completed send), and the message in question (binary() on
+<c>recv</c>, binary() or diameter_packet record on <c>send</c> or
+<c>ack</c>, or <c>false</c> on <c>ack</c> when an incoming request has
+been discarded).
+It should return a list of actions and a new callback as
+tail; eg. <c>[fun cb/3, State]</c>.
+Valid actions are the atoms <c>send</c> or <c>recv</c>, to
+cause a following message-valued action to be sent/received,
+a message to send/receive (binary() or
+diameter_packet record), or a boolean() to enable/disable reading on
+the socket.
+More than one <c>send</c>/<c>recv</c>/message sequence can be
+returned from the same callback, and an initial
+<c>send</c>/<c>recv</c> can be omitted if the same as the value passed
+as the callback's first argument.
+Reading is initially enabled, and returning <c>false</c> does not
+imply there cannot be subsequent <c>recv</c> callbacks since
+messages may already have been read.
+An empty tail is equivalent to the prevailing callback.
+Defaults to a callback equivalent to <c>fun(ack, _) -> []; (_, Msg) ->
+[Msg] end</c>.</p>
+
 <p>
 Remaining options are any accepted by &ssl_connect3; or
 &gen_tcp_connect3; for
-- 
cgit v1.2.3