From bbd5611dab2d7cbd76a5425a604c8452469ac8ae Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Sat, 23 Feb 2013 23:40:29 +0100 Subject: Document distribution config --- lib/diameter/doc/src/diameter.xml | 55 +++++++++++++++++++++++++++++++++++ lib/diameter/doc/src/diameter_app.xml | 32 ++++++++++++-------- 2 files changed, 75 insertions(+), 12 deletions(-) (limited to 'lib/diameter') 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 @@ erlang:nodes/0'> erlang:make_ref/0'> 1 bsl (32-N).

Defaults to {0,32}.

+ + +

+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.

+ + + +{share_peers, boolean()} + +

+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.

+ +

+Defaults to false.

+ + +

+Peers are only shared with other services of the same name. +Since the value of the &application_opt; alias 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.

+ + + +

+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;.

+ + + +{use_shared_peers, boolean()} + +

+Specifies whether or not the service makes use of peer connections +shared by identically named services on other Erlang nodes.

+ +

+Defaults to false.

+ + +

+A service that does not use shared peers will always pass the empty +list as the second argument of &app_pick_peer; callbacks.

+ 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.

-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 OKAY and Diameter @@ -230,8 +231,8 @@ handled independently of &peer_up; and &peer_down;.

-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 OKAY and the peer will no longer be a candidate in &pick_peer; callbacks.

@@ -240,11 +241,11 @@ candidate in &pick_peer; callbacks.

-Mod:pick_peer(Candidates, _Reserved, SvcName, State) +Mod:pick_peer(LocalCandidates, RemoteCandidates, SvcName, State) -> Selection | false Select a target peer for an outgoing request. -Candidates = [&peer;] +LocalCandidates = RemoteCandidates = [&peer;] SvcName = &mod_service_name; State = NewState = &state; Selection = {ok, Peer} | {Peer, NewState} @@ -257,7 +258,7 @@ peer for an outgoing request. The return value indicates the selected peer.

-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 filter 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 {filter, {all, [host, realm]}} option to &mod_call;) -will be placed at the head of the list.

+will be placed at the head of the list. +LocalCandidates contains peers whose transport process resides +on the local Erlang node while +RemoteCandidates contains peers that have been communicated +from other nodes by services of the same name.

A callback that returns a peer() will be followed by a @@ -285,10 +290,6 @@ an alternate peer will be followed by any additional callbacks since a retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.

-

-Returning false or {false, NewState} causes {error, -no_connection} to be returned from &mod_call;.

-

The return values false and {false, State} (that is, NewState = State) are equivalent, as are {ok, Peer} and @@ -296,6 +297,13 @@ The return values false and {false, State} (that is,

+RemoteCandidates is the empty list if the service has been +configured with the (default) &mod_service_opt; +{use_shared_peers, false}.

+ + + +

The return value {Peer, NewState} is only allowed if the Diameter application in question was configured with the &mod_application_opt; {call_mutates_state, true}. @@ -303,7 +311,7 @@ Otherwise, the State argument is always the intial value as configured on the application, not any subsequent value returned by a &peer_up; or &peer_down; callback.

- + -- cgit v1.2.3