From cefcaa5c1a3f49e2c8e277962326dfdb53ce6a4f Mon Sep 17 00:00:00 2001
From: Anders Svensson
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/diameter/doc/src')
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 @@
diameter_tcp(3)'>
gen_sctp(3)'>
gen_sctp:open/1'>
@@ -16,7 +18,7 @@
2011
-2016
+2017
Ericsson AB. All Rights Reserved.
@@ -78,7 +80,11 @@ and implements the behaviour documented in
Reason = term()
OwnOpt = {raddr, &ip_address;}
| {rport, integer()}
- | {accept, Match}
+ | {accept, Match}
+ | {unordered, boolean() | pos_integer()}
+ | {packet, boolean() | raw}
+ | {message_cb, &mod_eval;}
+ | {sender, boolean()}
SctpOpt = term()
Match = &ip_address; | string() | [Match]
@@ -105,6 +111,41 @@ Multiple accept options can be specified.
A string-valued Match that does not parse as an address is
interpreted as a regular expression.
+
+Option unordered specifies whether or not to use unordered
+delivery, integer N being equivalent to N =< OS,
+where OS 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 false.
+
+
+Option packet determines how/if an incoming message is
+packaged into a diameter_packet record.
+If false then messages are received as binary().
+If true then as a record with the binary() message in the
+bin field and a {stream, Id} tuple in the
+transport_data field, where Id is the identifier of the
+inbound stream the message was received on.
+If raw then as a record with the received ancillary
+sctp_sndrcvinfo record in the transport_data field.
+Defaults to true.
+
+
+Options message_cb and sender have semantics identical
+to those documented in &man_tcp_sender;, but with the message argument
+to a recv callback being as directed by the packet
+option.
+
+
+An {outstream, Id} tuple in the transport_data 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.
+
Remaining options are any accepted by &gen_sctp_open1;, with the exception
of options mode, binary, list, active
@@ -122,29 +163,16 @@ connecting transport.
-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 recbuf to increase
the buffer size.
-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 sndbuf to increase
the buffer size.
-
-The transport_data field of record diameter_packet
-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 {stream, Id} for an inbound
-message passed to a &app_handle_request; or &app_handle_answer;
-callback.
-For an outbound message, {outstream, Id} 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.
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 @@
-20112016
+2011
+2017
Ericsson AB. All Rights Reserved.
@@ -99,7 +100,9 @@ before configuring TLS capability on diameter transports.
| {rport, integer()}
| {accept, Match}
| {port, integer()}
- | {fragment_timer, infinity | 0..16#FFFFFFFF}
+ | {fragment_timer, infinity | 0..16#FFFFFFFF}
+ | {message_cb, &mod_eval;}
+ | {sender, boolean()}
SslOpt = {ssl_options, true | list()}
TcpOpt = term()
Match = &ip_address; | string() | [Match]
@@ -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.
+
+
+Option sender specifies whether or not to use a dedicated
+process for sending outgoing messages, which avoids the possibility of
+send blocking reception.
+Defaults to false.
+If set to true then a message_cb that avoids the
+possibility of messages being queued in the sender process without
+bound should be configured.
+
+
+Option message_cb 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 (send, recv, or ack after
+a completed send), and the message in question (binary() on
+recv, binary() or diameter_packet record on send or
+ack, or false on ack when an incoming request has
+been discarded).
+It should return a list of actions and a new callback as
+tail; eg. [fun cb/3, State].
+Valid actions are the atoms send or recv, 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 send/recv/message sequence can be
+returned from the same callback, and an initial
+send/recv can be omitted if the same as the value passed
+as the callback's first argument.
+Reading is initially enabled, and returning false does not
+imply there cannot be subsequent recv callbacks since
+messages may already have been read.
+An empty tail is equivalent to the prevailing callback.
+Defaults to a callback equivalent to fun(ack, _) -> []; (_, Msg) ->
+[Msg] end.
+
Remaining options are any accepted by &ssl_connect3; or
&gen_tcp_connect3; for
--
cgit v1.2.3