aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2013-02-23 23:40:29 +0100
committerAnders Svensson <[email protected]>2013-03-17 15:05:57 +0100
commitbbd5611dab2d7cbd76a5425a604c8452469ac8ae (patch)
treeb30305c33f8b6b8d543268f7ef758d1fb456c709
parent86400f7630699395cbe6f78864de4534c913be4c (diff)
downloadotp-bbd5611dab2d7cbd76a5425a604c8452469ac8ae.tar.gz
otp-bbd5611dab2d7cbd76a5425a604c8452469ac8ae.tar.bz2
otp-bbd5611dab2d7cbd76a5425a604c8452469ac8ae.zip
Document distribution config
-rw-r--r--lib/diameter/doc/src/diameter.xml55
-rw-r--r--lib/diameter/doc/src/diameter_app.xml32
2 files changed, 75 insertions, 12 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 379e9f0738..df9e03b2da 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+ <!ENTITY nodes
+ '<seealso marker="erts:erlang#nodes-0">erlang:nodes/0</seealso>'>
<!ENTITY make_ref
'<seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>'>
<!ENTITY transport_module
@@ -819,6 +821,59 @@ non-negative integer less than <c>1 bsl (32-N)</c>.</p>
<p>
Defaults to <c>{0,32}</c>.</p>
+
+<warning>
+<p>
+Multiple Erlang nodes implementing the same Diameter node should
+be configured with different sequence masks to ensure that each node
+uses a unique range of End-to-End and Hop-by-Hop identifiers for
+outgoing requests.</p>
+</warning>
+</item>
+
+<tag><c>{share_peers, boolean()}</c></tag>
+<item>
+<p>
+Specifies whether or not peer connections on the local Erlang node
+are shared with services on visible nodes (as returned by &nodes;).
+Peers shared from remote nodes become available in the candidates list
+passed as the second argument to &app_pick_peer; callbacks.</p>
+
+<p>
+Defaults to <c>false</c>.</p>
+
+<note>
+<p>
+Peers are only shared with other services of the same name.
+Since the value of the &application_opt; <c>alias</c> is the handle
+for identifying a peer, both local and remote, as a candidate for an
+outgoing request, services that share peers should use the same
+aliases for identifying their supported applications.</p>
+</note>
+
+<note>
+<p>
+Services that share peers can do so in order to distribute the
+implementation of a Diameter node across multiple Erlang nodes, in
+which case the participating services should typically be configured
+with identical &capabilities;.</p>
+</note>
+</item>
+
+<tag><c>{use_shared_peers, boolean()}</c></tag>
+<item>
+<p>
+Specifies whether or not the service makes use of peer connections
+shared by identically named services on other Erlang nodes.</p>
+
+<p>
+Defaults to <c>false</c>.</p>
+
+<note>
+<p>
+A service that does not use shared peers will always pass the empty
+list as the second argument of &app_pick_peer; callbacks.</p>
+</note>
</item>
</taglist>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index d0f1b22ebd..d094e1bade 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -196,7 +196,8 @@ process.</p>
</type>
<desc>
<p>
-Invoked to signal the availability of a peer connection.
+Invoked to signal the availability of a peer connection on the local
+Erlang node.
In particular, capabilities exchange with the peer has indicated
support for the application in question, the RFC 3539 watchdog state
machine for the connection has reached state <c>OKAY</c> and Diameter
@@ -230,8 +231,8 @@ handled independently of &peer_up; and &peer_down;.</p>
</type>
<desc>
<p>
-Invoked to signal that a peer connection is no longer available
-following a previous call to &peer_up;.
+Invoked to signal that a peer connection on the local Erlang node is
+no longer available following a previous call to &peer_up;.
In particular, that the RFC 3539 watchdog state machine for the
connection has left state <c>OKAY</c> and the peer will no longer be a
candidate in &pick_peer; callbacks.</p>
@@ -240,11 +241,11 @@ candidate in &pick_peer; callbacks.</p>
</func>
<func>
-<name>Mod:pick_peer(Candidates, _Reserved, SvcName, State)
+<name>Mod:pick_peer(LocalCandidates, RemoteCandidates, SvcName, State)
-> Selection | false</name>
<fsummary>Select a target peer for an outgoing request.</fsummary>
<type>
-<v>Candidates = [&peer;]</v>
+<v>LocalCandidates = RemoteCandidates = [&peer;]</v>
<v>SvcName = &mod_service_name;</v>
<v>State = NewState = &state;</v>
<v>Selection = {ok, Peer} | {Peer, NewState}</v>
@@ -257,7 +258,7 @@ peer for an outgoing request.
The return value indicates the selected peer.</p>
<p>
-The candidate list contains only those peers that have advertised
+The candidate lists contain only those peers that have advertised
support for the Diameter application in question during capabilities
exchange, that have not be excluded by a <c>filter</c> option in
the call to &mod_call;
@@ -266,7 +267,11 @@ The order of the elements is unspecified except that any
peers whose Origin-Host and Origin-Realm matches that of the
outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c>
option to &mod_call;)
-will be placed at the head of the list.</p>
+will be placed at the head of the list.
+<c>LocalCandidates</c> contains peers whose transport process resides
+on the local Erlang node while
+<c>RemoteCandidates</c> contains peers that have been communicated
+from other nodes by services of the same name.</p>
<p>
A callback that returns a peer() will be followed by a
@@ -286,16 +291,19 @@ retransmission to an alternate peer is abandoned if an answer is
received from a previously selected peer.</p>
<p>
-Returning <c>false</c> or <c>{false, NewState}</c> causes <c>{error,
-no_connection}</c> to be returned from &mod_call;.</p>
-
-<p>
The return values <c>false</c> and <c>{false, State}</c> (that is,
<c>NewState = State</c>) are equivalent, as are <c>{ok, Peer}</c> and
<c>{Peer, State}</c>.</p>
<note>
<p>
+<c>RemoteCandidates</c> is the empty list if the service has been
+configured with the (default) &mod_service_opt;
+<c>{use_shared_peers, false}</c>.</p>
+</note>
+
+<warning>
+<p>
The return value <c>{Peer, NewState}</c> is only allowed if
the Diameter application in question was configured with the
&mod_application_opt; <c>{call_mutates_state, true}</c>.
@@ -303,7 +311,7 @@ Otherwise, the <c>State</c> argument is always
the intial value as configured on the application, not any subsequent
value returned by a &peer_up;
or &peer_down; callback.</p>
-</note>
+</warning>
</desc>