<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Running the stack</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/megaco-3.16.0.2.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Megaco/H.248</strong><br><strong>User's Guide</strong><br><small>Version 3.16.0.2</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="megaco_intro.html">
Top of chapter
</a></li>
<li title="Scope and Purpose"><a href="megaco_intro.html#id56570">Scope and Purpose</a></li>
<li title="Prerequisites"><a href="megaco_intro.html#id65628">Prerequisites</a></li>
<li title="About This Manual"><a href="megaco_intro.html#id61790">About This Manual</a></li>
<li title="Where to Find More Information"><a href="megaco_intro.html#id62066">Where to Find More Information</a></li>
</ul>
</li>
<li id="no" title="Architecture" expanded="false">Architecture<ul>
<li><a href="megaco_architecture.html">
Top of chapter
</a></li>
<li title="Network view"><a href="megaco_architecture.html#id58224">Network view</a></li>
<li title="General"><a href="megaco_architecture.html#id65139">General</a></li>
<li title="Single node config"><a href="megaco_architecture.html#id60119">Single node config</a></li>
<li title="Distributed config"><a href="megaco_architecture.html#id58176">Distributed config</a></li>
<li title="Message round-trip call flow"><a href="megaco_architecture.html#id61141">Message round-trip call flow</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Running the stack" expanded="true">Running the stack<ul>
<li><a href="megaco_run.html">
Top of chapter
</a></li>
<li title="Starting"><a href="megaco_run.html#id64614">Starting</a></li>
<li title="MGC startup call flow"><a href="megaco_run.html#id65587">MGC startup call flow</a></li>
<li title="MG startup call flow"><a href="megaco_run.html#id64564">MG startup call flow</a></li>
<li title="Configuring the Megaco stack"><a href="megaco_run.html#id65484">Configuring the Megaco stack</a></li>
<li title="Initial configuration"><a href="megaco_run.html#id65269">Initial configuration</a></li>
<li title="Changing the configuration"><a href="megaco_run.html#id65365">Changing the configuration</a></li>
<li title="The transaction sender"><a href="megaco_run.html#id64741">The transaction sender</a></li>
<li title="Segmentation of transaction replies"><a href="megaco_run.html#id64873">Segmentation of transaction replies</a></li>
</ul>
</li>
<li id="no" title="Internal form and its encodings" expanded="false">Internal form and its encodings<ul>
<li><a href="megaco_encode.html">
Top of chapter
</a></li>
<li title="Internal form of messages"><a href="megaco_encode.html#id64187">Internal form of messages</a></li>
<li title="The different encodings"><a href="megaco_encode.html#id64304">The different encodings</a></li>
<li title="Configuration of Erlang distribution encoding module"><a href="megaco_encode.html#id64461">Configuration of Erlang distribution encoding module</a></li>
<li title="Configuration of text encoding module(s)"><a href="megaco_encode.html#id65758">Configuration of text encoding module(s)</a></li>
<li title="Configuration of binary encoding module(s)"><a href="megaco_encode.html#id65967">Configuration of binary encoding module(s)</a></li>
<li title="Handling megaco versions"><a href="megaco_encode.html#id66078">Handling megaco versions</a></li>
<li title="Encoder callback functions"><a href="megaco_encode.html#id66326">Encoder callback functions</a></li>
</ul>
</li>
<li id="no" title="Transport mechanisms" expanded="false">Transport mechanisms<ul>
<li><a href="megaco_transport_mechanisms.html">
Top of chapter
</a></li>
<li title="Callback interface"><a href="megaco_transport_mechanisms.html#id66413">Callback interface</a></li>
<li title="Examples"><a href="megaco_transport_mechanisms.html#id66482">Examples</a></li>
</ul>
</li>
<li id="no" title="Implementation examples" expanded="false">Implementation examples<ul>
<li><a href="megaco_examples.html">
Top of chapter
</a></li>
<li title="A simple Media Gateway Controller"><a href="megaco_examples.html#id66572">A simple Media Gateway Controller</a></li>
<li title="A simple Media Gateway"><a href="megaco_examples.html#id66620">A simple Media Gateway</a></li>
</ul>
</li>
<li id="no" title="Megaco mib" expanded="false">Megaco mib<ul>
<li><a href="megaco_mib.html">
Top of chapter
</a></li>
<li title="Intro"><a href="megaco_mib.html#id66738">Intro</a></li>
<li title="Statistics counters"><a href="megaco_mib.html#id66763">Statistics counters</a></li>
<li title="Distribution"><a href="megaco_mib.html#id66799">Distribution</a></li>
</ul>
</li>
<li id="no" title="Performance comparison" expanded="false">Performance comparison<ul>
<li><a href="megaco_performance.html">
Top of chapter
</a></li>
<li title="Comparison of encoder/decoders"><a href="megaco_performance.html#id66878">Comparison of encoder/decoders</a></li>
<li title="System performance characteristics"><a href="megaco_performance.html#id67709">System performance characteristics</a></li>
<li title="Description of encoders/decoders"><a href="megaco_performance.html#id67746">Description of encoders/decoders</a></li>
<li title="Setup"><a href="megaco_performance.html#id67856">Setup</a></li>
<li title="Summary"><a href="megaco_performance.html#id67869">Summary</a></li>
</ul>
</li>
<li id="no" title="Testing and tools" expanded="false">Testing and tools<ul>
<li><a href="megaco_debug.html">
Top of chapter
</a></li>
<li title="Tracing"><a href="megaco_debug.html#id67998">Tracing</a></li>
<li title="Measurement and transformation"><a href="megaco_debug.html#id68043">Measurement and transformation</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>3 Running the stack</h1>
<h3><a name="id64614">3.1
Starting</a></h3>
<a name="starting"></a>
<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>
<ul>
<li>
<p>SendMod:send_message(SendHandle, ErlangBinary)</p>
</li>
</ul>
<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>
<h3><a name="id65587">3.2
MGC startup call flow</a></h3>
<a name="mgc_startup_call_flow"></a>
<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>
<ul>
<li>
<p>Start the Megaco application.</p>
</li>
<li>
<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>
</li>
<li>
<p>Initiate the transport service and provide it with a
receive handle obtained from megaco:user_info/2.</p>
</li>
</ul>
<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>
<img alt="IMAGE MISSING" src="MGC_startup_call_flow.gif"><br>
<em>Figure
3.1:
MGC Startup Call Flow</em>
<h3><a name="id64564">3.3
MG startup call flow</a></h3>
<a name="mg_startup_call_flow"></a>
<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>
<ul>
<li>
<p>Start the Megaco application.</p>
</li>
<li>
<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>
</li>
<li>
<p>Initiate the transport service and provide it with a
receive handle obtained from megaco:user_info/2.</p>
</li>
<li>
<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>
</li>
</ul>
<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>
<img alt="IMAGE MISSING" src="MG_startup_call_flow.gif"><br>
<em>Figure
3.2:
MG Startup Call Flow</em>
<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>
<img alt="IMAGE MISSING" src="MG-startup_flow_noMID.gif"><br>
<em>Figure
3.3:
MG Startup Call Flow (no MID)</em>
<h3><a name="id65484">3.4
Configuring the Megaco stack</a></h3>
<a name="config_megaco"></a>
<p>There are three kinds of configuration:</p>
<ul>
<li>
<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
<span class="bold_code"><a href="megaco.html#user_info">megaco:user_info</a></span>. </p>
</li>
<li>
<p>Connection info - Information regarding connections. Read/Write.</p>
<p>This information can be retrieved using
<span class="bold_code"><a href="megaco.html#conn_info">megaco:conn_info</a></span>. </p>
</li>
<li>
<p>System info - System wide information. Read only.</p>
<p>This information can be retrieved using
<span class="bold_code"><a href="megaco.html#system_info">megaco:system_info</a></span>. </p>
</li>
</ul>
<h3><a name="id65269">3.5
Initial configuration</a></h3>
<a name="initial_config"></a>
<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>
<ul>
<li>
<p><span class="code">users = [{Mid, [user_config()]}].</span></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:
<span class="code">{Item, Value}</span>).</p>
</li>
<li>
<p><span class="code">scanner = flex | {Module, Function, Arguments, Modules}</span></p>
<ul>
<li>
<p><span class="code">flex</span> will result in the start of the flex scanner with default
options.</p>
</li>
<li>
<p>The MFA alternative makes it possible for Megaco to start and
supervise a scanner written by the user (see
<span class="code">supervisor:start_child</span> for an explanation of the
parameters).</p>
</li>
</ul>
</li>
</ul>
<p>See also <span class="bold_code"><a href="megaco_encode.html#text_config">Configuration of text encoding module(s)</a></span>
for more info. </p>
<h3><a name="id65365">3.6
Changing the configuration</a></h3>
<a name="changing_config"></a>
<p>The configuration can be changed during runtime. This is done with
the functions <span class="bold_code"><a href="megaco.html#update_user_info">megaco:update_user_info</a></span> and
<span class="bold_code"><a href="megaco.html#update_conn_info">megaco:update_conn_info</a></span></p>
<h3><a name="id64741">3.7
The transaction sender</a></h3>
<a name="transaction_sender"></a>
<p>The transaction sender is a process (one per connection), which handle
all transaction sending, if so configured (see
<span class="bold_code"><a href="megaco.html#user_info">megaco:user_info</a></span> and
<span class="bold_code"><a href="megaco.html#conn_info">megaco:conn_info</a></span>).</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>
<ul>
<li>
<p>When <span class="code">trans_timer</span> expires.</p>
</li>
<li>
<p>When <span class="code">trans_ack_maxcount</span> number of ack's has been
received.</p>
</li>
<li>
<p>When <span class="code">trans_req_maxcount</span> number of requests's has
been received.</p>
</li>
<li>
<p>When the size of all received requests exceeds
<span class="code">trans_req_maxsize</span>.</p>
</li>
<li>
<p>When a reply transaction is sent.</p>
</li>
<li>
<p>When a pending transaction is sent.</p>
</li>
</ul>
<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
<span class="code">trans_req_maxsize</span>, 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 <span class="code">trans_timer</span> and the
<span class="code">request_timer</span> is not properly chosen.</p>
<h3><a name="id64873">3.8
Segmentation of transaction replies</a></h3>
<a name="segment_reply"></a>
<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
<span class="bold_code"><a href="megaco_encode.html#handling_versions">version3</a></span>.</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>
<ul>
<li>
<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
<span class="bold_code"><a href="megaco.html#user_info">segment_recv_timer</a></span>
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
<span class="bold_code"><a href="megaco.html#cast">megaco:cast</a></span> function,
the segments are delivered to the user via the
<span class="bold_code"><a href="megaco_user.html#trans_reply">handle_trans_reply</a></span>
callback function one at a time, as they arrive. But this obviously
doe not work for the
<span class="bold_code"><a href="megaco.html#call">megaco:call</a></span> function.
In this case, the segments are accumulated and then delivered
all at once as the function returns.</p>
</li>
<li>
<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 <span class="bold_code"><a href="megaco.html#user_info">segment_send</a></span> 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
<span class="bold_code"><a href="megaco.html#user_info">max_pdu_size</a></span> option).
Finally, if segmentation is decided, then each action reply
will make up its own (segment) message.</p>
</li>
</ul>
</div>
<div class="footer">
<hr>
<p>Copyright © 2000-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
