The R13B03 release.OTP_R13B03

1 files changed, 373 insertions, 0 deletions

diff --git a/lib/megaco/doc/src/megaco_run.xml b/lib/megaco/doc/src/megaco_run.xml
new file mode 100644
index 0000000000..3afc638bcf
--- /dev/null
+++ b/lib/megaco/doc/src/megaco_run.xml
@@ -0,0 +1,373 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2000</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Running the stack</title>
+    <prepared>H&aring;kan Mattsson</prepared>
+    <responsible>H&aring;kan Mattsson</responsible>
+    <docno></docno>
+    <approved>H&aring;kan Mattsson</approved>
+    <checked></checked>
+    <date>2007-06-15</date>
+    <rev>%VSN%</rev>
+    <file>megaco_run.xml</file>
+  </header>
+
+  <section>
+    <marker id="starting"></marker>
+    <title>Starting</title>
+    <p>A user may have a number of "virtual" connections to other
+      users. An MG is connected to at most one MGC, while an MGC may
+      be connected to any number of MG's. For each connection the user
+      selects a transport service, an encoding scheme and a user
+      callback module.</p>
+    <p>An MGC must initiate its transport service in order to listen
+      to MG's trying to connect. How the actual transport is initiated
+      is outside the scope of this application. However a send handle
+      (typically a socket id or host and port) must be provided from
+      the transport service in order to enable us to send the message
+      to the correct destination. We do however not assume anything
+      about this, from our point of view, opaque handle. Hopefully it
+      is rather small since it will passed around the system between
+      processes rather frequently.</p>
+    <p>A user may either be statically configured in a .config file
+      according to the application concept of Erlang/OTP or
+      dynamically started with the configuration settings as arguments
+      to megaco:start_user/2. These configuration settings may be
+      updated later on with megaco:update_conn_info/2.</p>
+    <p>The function megaco:connect/4 is used to tell the Megaco
+      application about which control process it should supervise,
+      which MID the remote user has, which callback module it should
+      use to send messages etc. When this "virtual" connection is
+      established the user may use megaco:call/3 and megaco:cast/3 in
+      order to send messages to the other side. Then it is up to the
+      MG to send its first Service Change Request message after
+      applying some clever algorithm in order to fight the problem
+      with startup avalanche (as discussed in the RFC).</p>
+    <p>The originating user will wait for a reply or a timeout
+      (defined by the request_timer). When it receives the reply this
+      will optionally be acknowledged (regulated by auto_ack), and
+      forwarded to the user.  If an interim pending reply is received,
+      the long_request_timer will be used instead of the usual
+      request_timer, in order to enable avoidance of spurious re-sends
+      of the request.</p>
+    <p>On the destination side the transport service waits for
+      messages. Each message is forwarded to the Megaco application
+      via the megaco:receive_message/4 callback function. The
+      transport service may or may not provide means for blocking and
+      unblocking the reception of the incoming messages.</p>
+    <p></p>
+    <p>If a message is received before the "virtual" connection has
+      been established, the connection will be setup automatically. An
+      MGC may be real open minded and dynamically decide which
+      encoding and transport service to use depending on how the
+      transport layer contact is performed. For IP transports two
+      ports are standardized, one for textual encoding and one for
+      binary encoding. If for example an UDP packet was received on
+      the text port it would be possible to decide encoding and
+      transport on the fly.</p>
+    <p>After decoding a message various user callback functions are
+      invoked in order to allow the user to act properly.  See the
+      megaco_user module for more info about the callback
+      arguments.</p>
+    <p>When the user has processed a transaction request in its
+      callback function, the Megaco application assembles a
+      transaction reply, encodes it using the selected encoding module
+      and sends the message back by invoking the callback
+      function:</p>
+    <list type="bulleted">
+      <item>
+        <p>SendMod:send_message(SendHandle, ErlangBinary)</p>
+      </item>
+    </list>
+    <p>Re-send of messages, handling pending transactions,
+      acknowledgements etc. is handled automatically by the Megaco
+      application but the user is free to override the default
+      behaviour by the various configuration possibilities. See
+      megaco:update_user_info/2 and megaco:update_conn_info/2 about
+      the possibilities.</p>
+    <p>When connections gets broken (that is explicitly by
+      megaco:disconnect/2 or when its controlling process dies) a user
+      callback function is invoked in order to allow the user to
+      re-establish the connection. The internal state of kept
+      messages, re-send timers etc. is not affected by this. A few
+      re-sends will of course fail while the connection is down, but
+      the automatic re-send algorithm does not bother about this and
+      eventually when the connection is up and running the messages
+      will be delivered if the timeouts are set to be long enough. The
+      user has the option of explicitly invoking megaco:cancel/2 to
+      cancel all messages for a connection.</p>
+  </section>
+
+  <section>
+    <marker id="mgc_startup_call_flow"></marker>
+    <title>MGC startup call flow</title>
+    <p>In order to prepare the MGC for the reception of the initial
+      message, hopefully a Service Change Request, the following needs
+      to be done:</p>
+    <list type="bulleted">
+      <item>
+        <p>Start the Megaco application.</p>
+      </item>
+      <item>
+        <p>Start the MGC user. This may either be done explicitly
+          with megaco:start_user/2 or implicitly by providing the -megaco
+          users configuration parameter.</p>
+      </item>
+      <item>
+        <p>Initiate the transport service and provide it with a
+          receive handle obtained from megaco:user_info/2.</p>
+      </item>
+    </list>
+    <p>When the initial message arrives the transport service
+      forwards it to the protocol engine which automatically
+      sets up the connection and invokes UserMod:handle_connect/2
+      before it invokes UserMod:handle_trans_request/3 with
+      the Service Change Request like this:</p>
+    <image file="MGC_startup_call_flow.gif">
+      <icaption>MGC Startup Call Flow</icaption>
+    </image>
+  </section>
+
+  <section>
+    <marker id="mg_startup_call_flow"></marker>
+    <title>MG startup call flow</title>
+    <p>In order to prepare the MG for the sending of the initial
+      message, hopefully a Service Change Request, the following needs
+      to be done:</p>
+    <list type="bulleted">
+      <item>
+        <p>Start the Megaco application.</p>
+      </item>
+      <item>
+        <p>Start the MG user. This may either be done explicitly
+          with megaco:start_user/2 or implicitly by providing the -megaco
+          users configuration parameter.</p>
+      </item>
+      <item>
+        <p>Initiate the transport service and provide it with a
+          receive handle obtained from megaco:user_info/2.</p>
+      </item>
+      <item>
+        <p>Setup a connection to the MGC with megaco:connect/4 and
+          provide it with a receive handle obtained from
+          megaco:user_info/2.</p>
+      </item>
+    </list>
+    <p>If the MG has been provisioned with the MID of the MGC it can
+      be given as the RemoteMid parameter to megaco:connect/4 and the
+      call flow will look like this:</p>
+    <image file="MG_startup_call_flow.gif">
+      <icaption>MG Startup Call Flow</icaption>
+    </image>
+    <p>If the MG cannot be provisioned with the MID of the MGC, the
+      MG can use the atom 'preliminary_mid' as the RemoteMid parameter
+      to megaco:connect/4 and the call flow will look like this:</p>
+    <image file="MG-startup_flow_noMID.gif">
+      <icaption>MG Startup Call Flow (no MID)</icaption>
+    </image>
+  </section>
+
+  <section>
+    <marker id="config_megaco"></marker>
+    <title>Configuring the Megaco stack</title>
+    <p>There are three kinds of configuration:</p>
+    <list type="bulleted">
+      <item>
+        <p>User info - Information related to megaco users. Read/Write. </p>
+        <p>A User is an entity identified by a MID, e.g. a MGC or a MG. </p>
+        <p>This information can be retrieved using 
+          <seealso marker="megaco#user_info">megaco:user_info</seealso>. </p>
+      </item>
+      <item>
+        <p>Connection info - Information regarding connections. Read/Write.</p>
+        <p>This information can be retrieved using 
+          <seealso marker="megaco#conn_info">megaco:conn_info</seealso>. </p>
+      </item>
+      <item>
+        <p>System info - System wide information. Read only.</p>
+        <p>This information can be retrieved using 
+          <seealso marker="megaco#system_info">megaco:system_info</seealso>. </p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <marker id="initial_config"></marker>
+    <title>Initial configuration</title>
+    <p>The initial configuration of the Megaco should be defined in the
+      Erlang system configuration file. The following configured parameters
+      are defined for the Megaco application:</p>
+    <list type="bulleted">
+      <item>
+        <p><c><![CDATA[users = [{Mid, [user_config()]}].]]></c></p>
+        <p>Each user is represented by a tuple with the Mid of the user and a
+          list of config parameters (each parameter is in turn a tuple:
+          <c><![CDATA[{Item, Value}]]></c>).</p>
+      </item>
+      <item>
+        <p><c><![CDATA[scanner = flex | {Module, Function, Arguments, Modules}]]></c></p>
+<!--
+  For future use
+        <p><c><![CDATA[scanner = flex | {flex, Opts} | {Module, Function, Arguments, Modules}]]></c></p>
+-->
+        <list type="bulleted">
+          <item>
+            <p><c><![CDATA[flex]]></c> will result in the start of the flex scanner with default 
+              options.</p>
+          </item>
+<!--
+  For future use
+          <item>
+            <p><c><![CDATA[{flex, Opts}]]></c> will result in the start of the flex scanner with the 
+              specified options. <c>Opts</c> is two-tuple list where the only allowed option is
+              <c>{smp, boolean()}</c>, with default value being <c>false</c> and the value of 
+              <c>true</c> resulting in a start of an smp-optimized scanner. </p>
+          </item>
+-->
+          <item>
+            <p>The MFA alternative makes it possible for Megaco to start and
+              supervise a scanner written by the user (see 
+            <c><![CDATA[supervisor:start_child]]></c> for an explanation of the 
+              parameters).</p>
+          </item>
+        </list>
+      </item>
+    </list>
+    <p>See also <seealso marker="megaco_encode#text_config">Configuration of text encoding module(s)</seealso> 
+      for more info. </p>
+  </section>
+
+  <section>
+    <marker id="changing_config"></marker>
+    <title>Changing the configuration</title>
+    <p>The configuration can be changed during runtime. This is done with
+      the functions <seealso marker="megaco#update_user_info">megaco:update_user_info</seealso> and 
+      <seealso marker="megaco#update_conn_info">megaco:update_conn_info</seealso></p>
+  </section>
+
+  <section>
+    <marker id="transaction_sender"></marker>
+    <title>The transaction sender</title>
+    <p>The transaction sender is a process (one per connection), which handle
+      all transaction sending, if so configured (see 
+      <seealso marker="megaco#user_info">megaco:user_info</seealso> and 
+      <seealso marker="megaco#conn_info">megaco:conn_info</seealso>).</p>
+    <p>The purpose of the transaction sender is to accumulate transactions 
+      for a more efficient message sending. The transactions that are 
+      accumulated are transaction request and transaction ack. For 
+      transaction ack's the benefit is quite large, since the transactions 
+      are small and it is possible to have ranges (which means that 
+      transaction acks for transactions 1, 2, 3 and 4 can be sent as a 
+      range 1-4 in one transaction ack, instead of four separate 
+      transactions). </p>
+    <p>There are a number of configuration parameter's that control the 
+      operation of the transaction sender. In principle, a message with 
+      everything stored (ack's and request's) is sent from the process 
+      when:</p>
+    <list type="bulleted">
+      <item>
+        <p>When <c><![CDATA[trans_timer]]></c> expires.</p>
+      </item>
+      <item>
+        <p>When <c><![CDATA[trans_ack_maxcount]]></c> number of ack's has been 
+          received.</p>
+      </item>
+      <item>
+        <p>When <c><![CDATA[trans_req_maxcount]]></c> number of requests's has 
+          been received.</p>
+      </item>
+      <item>
+        <p>When the size of all received requests exceeds 
+          <c><![CDATA[trans_req_maxsize]]></c>.</p>
+      </item>
+      <item>
+        <p>When a reply transaction is sent.</p>
+      </item>
+      <item>
+        <p>When a pending transaction is sent.</p>
+      </item>
+    </list>
+    <p>When something is to be sent, everything is packed into one message,  
+      unless the trigger was a reply transaction and the added size of the 
+      reply and all the requests is greater then 
+      <c><![CDATA[trans_req_maxsize]]></c>, in which case the stored 
+      transactions are sent first in a separate message and the reply in 
+      another message.</p>
+    <p>When the transaction sender receives a request which is already 
+      "in storage" (indicated by the transaction id) it is assumed to 
+      be a resend and everything stored is sent. This could happen if 
+      the values of the <c><![CDATA[trans_timer]]></c> and the
+      <c><![CDATA[request_timer]]></c> is not properly choosen.</p>
+  </section>
+
+  <section>
+    <marker id="segment_reply"></marker>
+    <title>Segmentation of transaction replies</title>
+    <p>In version 3 of the megaco standard the Segmentation package was
+      introduced. Simply, this package defines a procedure to segment 
+      megaco messages (transaction replies) when using a transport that 
+      does not automatically do this (e.g. UDP). See also
+      <seealso marker="megaco_encode#handling_versions">version3</seealso>.</p>
+    <p>Although it would be both pointless and counterproductive to use
+      segmentation on a transport that already does this (e.g. TCP), the 
+      megaco application does not check this. Instead, it is up to the 
+      user to configure this properly. </p>
+    <list type="bulleted">
+      <item>
+        <p>Receiving segmented messages: </p>
+        <p>This is handled automatically by the megaco application. 
+          There is however one thing that need to be configured by the user, 
+          the 
+          <seealso marker="megaco#user_info">segment_recv_timer</seealso>
+          option. </p>
+        <p>Note that the segments are delivered to the user differently 
+          depending on which function is used to issue the original request.
+          When issuing the request using the 
+          <seealso marker="megaco#cast">megaco:cast</seealso> function,
+          the segments are delivered to the user via the 
+          <seealso marker="megaco_user#trans_reply">handle_trans_reply</seealso>
+          callback function one at a time, as they arrive. But this obviously
+          doe not work for the 
+          <seealso marker="megaco#call">megaco:call</seealso> function. 
+          In this case, the segments are accumulated and then delivered
+          all at once as the function returns.</p>
+      </item>
+      <item>
+        <p>Sending segmented messages: </p>
+        <p>This is also handled automatically by the megaco application. 
+          First of all, segmentation is only attempted if so configured, see 
+          the <seealso marker="megaco#user_info">segment_send</seealso> option.
+          Secondly, megaco relies on the ability of the used codec to
+          encode action replies, which is the smallest component the
+          megaco application handles when segmenting. Thirdly, the 
+          reply will be segmented only if the sum of the size of the
+          action replies (plus an arbitrary message header size) are greater
+          then the specified max message size (see the 
+          <seealso marker="megaco#user_info">max_pdu_size</seealso> option).
+          Finally, if segmentation is decided, then each action reply
+          will make up it's own (segment) message.</p>
+      </item>
+    </list>
+  </section>
+</chapter>
+