diff options
Diffstat (limited to 'lib/asn1/doc/src/asn1_spec.xmlsrc')
| -rw-r--r-- | lib/asn1/doc/src/asn1_spec.xmlsrc | 824 |
1 files changed, 824 insertions, 0 deletions
diff --git a/lib/asn1/doc/src/asn1_spec.xmlsrc b/lib/asn1/doc/src/asn1_spec.xmlsrc new file mode 100644 index 0000000000..8d61834da8 --- /dev/null +++ b/lib/asn1/doc/src/asn1_spec.xmlsrc @@ -0,0 +1,824 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</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>Specialized Decodes</title> + <prepared>EAB/UAB/UKH/KD Bertil Karlsson</prepared> + <docno></docno> + <date>2003-04-24</date> + <rev>D</rev> + <file>asn1_spec.xml</file> + </header> + <marker id="SpecializedDecodes"></marker> + <p>When performance is of highest priority and one is interested in + a limited part of the ASN.1 encoded message, before one decide what + to do with the rest of it, one may want to decode only this small + part. The situation may be a server that has to decide to which + addressee it will send a message. The addressee may be interested in + the entire message, but the server may be a bottleneck that one want + to spare any unnecessary load. Instead of making two <em>complete decodes</em> (the normal case of decode), one in the server and one + in the addressee, it is only necessary to make one <em>specialized decode</em>(in the server) and another complete decode(in the + addressee). The following specialized decodes <em>exclusive decode</em> and <em>selected decode</em> support to solve this and + similar problems. + </p> + <p>So far this functionality is only provided when using the + optimized BER_BIN version, that is when compiling with the + options <c>ber_bin</c> and <c>optimize</c>. It does also work + using the <c>driver</c> option. We have no intent to make this + available on the default BER version, but maybe in the PER_BIN + version (<c>per_bin</c>). + </p> + + <section> + <title>Exclusive Decode</title> + <p>The basic idea with exclusive + decode is that you specify which parts of the message you want to + exclude from being decoded. These parts remain encoded and are + returned in the value structure as binaries. They may be decoded + in turn by passing them to a certain <c>decode_part/2</c> + function. The performance gain is high when the message is large + and you can do an exclusive decode and later on one or several + decodes of the parts or a second complete decode instead of two or + more complete decodes. + </p> + + <section> + <title>How To Make It Work</title> + <p>In order to make exclusive decode work you have to do the + following: + </p> + <list type="bulleted"> + <item>First,decide the name of the function for the exclusive + decode.</item> + <item>Second, write instructions that must consist of the name + of the exclusive decode function, the name of the ASN.1 + specification and a notation that tells which parts of the + message structure will be excluded from decode. These + instructions shall be included in a configuration + file. </item> + <item>Third, compile with the additional option + <c>asn1config</c>. The compiler searches for a configuration + file with the same name as the ASN.1 spec but with the + extension .asn1config. This configuration file is not the same + as used for compilation of a set of files. See section + <seealso marker="#UndecodedPart">Writing an Exclusive Decode Instruction.</seealso></item> + </list> + </section> + + <section> + <title>User Interface</title> + <p>The run-time user interface for exclusive decode consists of + two different functions. First, the function for an exclusive + decode, whose name the user decides in the configuration + file. Second, the compiler generates a <c>decode_part/2</c> + function when exclusive decode is chosen. This function decodes + the parts that were left undecoded during the exclusive + decode. Both functions are described below. + </p> + <p>If the exclusive decode function has for example got the name + <c>decode_exclusive</c> and an ASN.1 encoded message + <c>Bin</c> shall be exclusive decoded, the call is:</p> + <pre> +{ok,Excl_Message} = 'MyModule':decode_exclusive(Bin) </pre> + <marker id="UndecodedPart"></marker> + <p>The result <c>Excl_Message</c> has the same structure as an + complete decode would have, except for the parts of the top-type + that were not decoded. The undecoded parts will be on their place + in the structure on the format <c>{Type_Key,Undecoded_Value}</c>. + </p> + <p>Each undecoded part that shall be decoded must be fed into the <c>decode_part/2</c> function,like:</p> + <pre> +{ok,Part_Message} = 'MyModule':decode_part(Type_Key,Undecoded_Value) </pre> + </section> + + <section> + <marker id="Exclusive Instruction"></marker> + <title>Writing an Exclusive Decode Instruction</title> + <p>This instruction is written in the configuration file on the + format:</p> + <pre> + +Exclusive_Decode_Instruction = {exclusive_decode,{Module_Name,Decode_Instructions}}. + +Module_Name = atom() + +Decode_Instructions = [Decode_Instruction]+ + +Decode_Instruction = {Exclusive_Decode_Function_Name,Type_List} + +Exclusive_Decode_Function_Name = atom() + +Type_List = [Top_Type,Element_List] + +Element_List = [Element]+ + +Element = {Name,parts} | + {Name,undecoded} | + {Name,Element_List} + +Top_Type = atom() + +Name = atom() + </pre> + <p>Observe that the instruction must be a valid Erlang term ended + by a dot. + </p> + <p>In the <c>Type_List</c> the "path" from the top type to each + undecoded sub-components is described. The top type of the path is + an atom, the name of it. The action on each component/type that + follows will be described by one of <c>{Name,parts}, {Name,undecoded}, {Name,Element_List}</c></p> + <p>The use and effect of the actions are: + </p> + <list type="bulleted"> + <item><c>{Name,undecoded}</c> Tells that the element will be + left undecoded during the exclusive decode. The type of Name may + be any ASN.1 type. The value of element Name will be returned as a + tuple,as mentioned <seealso marker="#UndecodedPart">above</seealso>, in the value structure of the top type.</item> + <item><c>{Name,parts}</c> The type of Name may be one of + SEQUENCE OF or SET OF. The action implies that the different + components of Name will be left undecoded. The value of Name + will be returned as a tuple, as <seealso marker="#UndecodedPart">above </seealso>, where the second element is a list of + binaries. That is because the representation of a SEQUENCE OF/ + SET OF in Erlang is a list of its internal type. Any of the + elements of this list or the entire list can be decoded by the + <c>decode_part</c> function.</item> + <item><c>{Name,Element_List}</c>This action is used when one or + more of the sub-types of Name will be exclusive decoded.</item> + </list> + <p>Name in the actions above may be a component name of a + SEQUENCE or a SET or a name of an alternative in a CHOICE. + </p> + </section> + + <section> + <title>Example</title> + <p>In the examples below we use the definitions from the following ASN.1 spec:</p> + <marker id="Asn1spec"></marker> + <codeinclude file="Seq.asn" tag="" type="none"></codeinclude> + <p>If <c>Button</c> is a top type and we want to exclude + component <c>number</c> from decode the Type_List in the + instruction in the configuration file will be + <c>['Button',[{number,undecoded}]]</c>. If we call the decode + function <c>decode_Button_exclusive</c> the Decode_Instruction + will be + <c>{decode_Button_exclusive,['Button',[{number,undecoded}]]}</c>. + </p> + <p>We also have another top type <c>Window</c> whose sub + component actions in type <c>Status</c> and the parts of component + <c>buttonList</c> shall be left undecoded. For this type we name + the function <c>decode__Window_exclusive</c>. The whole + Exclusive_Decode_Instruction configuration is as follows: </p> + <codeinclude file="Seq.asn1config" tag="" type="none"></codeinclude> + <p></p> + <image file="exclusive_Win_But.gif"> + <icaption>Figure symbolizes the bytes of a Window:status message. The components buttonList and actions are excluded from decode. Only state and enabled are decoded when decode__Window_exclusive is called. </icaption> + </image> + <p></p> + <p>Compiling GUI.asn including the configuration file is done like:</p> + <pre> +unix> erlc -bber_bin +optimize +asn1config GUI.asn + +erlang> asn1ct:compile('GUI',[ber_bin,optimize,asn1config]). </pre> + <p>The module can be used like:</p> + <pre> + +1> Button_Msg = {'Button',123,true}. +{'Button',123,true} +2> {ok,Button_Bytes} = 'GUI':encode('Button',Button_Msg). +{ok,[<<48>>, + [6], + [<<128>>, + [1], + 123], + [<<129>>, + [1], + 255]]} +3> {ok,Exclusive_Msg_Button} = 'GUI':decode_Button_exclusive(list_to_binary(Button_Bytes)). +{ok,{'Button',{'Button_number',<<28,1,123>>}, + true}} +4> 'GUI':decode_part('Button_number',<<128,1,123>>). +{ok,123} +5> Window_Msg = +{'Window',{status,{'Status',35, + [{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}], + false, + {possibleActions,[{'Action',16,{'Button',17,true}}]}}}}. +{'Window',{status,{'Status',35, + [{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}], + false, + {possibleActions,[{'Action',16,{'Button',17,true}}]}}}} +6> {ok,Window_Bytes}='GUI':encode('Window',Window_Msg). +{ok,[<<161>>, + [127], + [<<128>>, ... + + +8> {ok,{status,{'Status',Int,{Type_Key_SeqOf,Val_SEQOF}, +BoolOpt,{Type_Key_Choice,Val_Choice}}}}= +'GUI':decode_Window_status_exclusive(list_to_binary(Window_Bytes)). +{ok,{status,{'Status',35, + {'Status_buttonList',[<<48,6,128,1,3,129,1,255>>, + <<48,6,128,1,4,129,1,0>>, + <<48,6,128,1,5,129,1,255>>, + <<48,6,128,1,6,129,1,255>>, + <<48,6,128,1,7,129,1,0>>, + <<48,6,128,1,8,129,1,255>>, + <<48,6,128,1,9,129,1,255>>, + <<48,6,128,1,10,129,1,0>>, + <<48,6,128,1,11,129,1,255>>, + <<48,6,128,1,12,129,1,255>>, + <<48,6,128,1,13,129,1,0>>, + <<48,6,128,1,14,129,1,255>>]}, + false, + {'Status_actions', +<<163,21,160,19,48,17,2,1,16,160,12,172,10,171,8,48,6,128,1,...>>}}}} +10> 'GUI':decode_part(Type_Key_SeqOf,Val_SEQOF). +{ok,[{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}]} +11> 'GUI':decode_part(Type_Key_SeqOf,hd(Val_SEQOF)). +{ok,{'Button',3,true}} +12> 'GUI':decode_part(Type_Key_Choice,Val_Choice). +{ok,{possibleActions,[{'Action',16,{'Button',17,true}}]}} + </pre> + </section> + </section> + + <section> + <title>Selective Decode</title> + <p>This specialized decode decodes one single subtype of a + constructed value. It is the fastest method to extract one sub + value. The typical use of this decode is when one want to + inspect, for instance a version number,to be able to decide what + to do with the entire value. The result is returned as + <c>{ok,Value}</c> or <c>{error,Reason}</c>. + </p> + + <section> + <title>How To Make It Work</title> + <p>The following steps are necessary: + </p> + <list type="bulleted"> + <item>Write instructions in the configuration + file. Including the name of a user function, the name of the ASN.1 + specification and a notation that tells which part of the type + will be decoded. </item> + <item>Compile with the additional option + <c>asn1config</c>. The compiler searches for a configuration file + with the same name as the ASN.1 spec but with the extension + .asn1config. In the same file you can provide configuration specs + for exclusive decode as well. The generated Erlang module has the + usual functionality for encode/decode preserved and the + specialized decode functionality added. </item> + </list> + </section> + + <section> + <title>User Interface</title> + <p>The only new user interface function is the one provided by the + user in the configuration file. You can invoke that function by + the <c>ModuleName:FunctionName</c> notation. + </p> + <p>So, if you have the following spec + <c>{selective_decode,{'ModuleName',[{selected_decode_Window,TypeList}]}}</c> + in the con-fig file, you do the selective decode by + <c>{ok,Result}='ModuleName':selected_decode_Window(EncodedBinary).</c></p> + </section> + + <section> + <marker id="Selective Instruction"></marker> + <title>Writing a Selective Decode Instruction</title> + <p>It is possible to describe one or many selective decode + functions in a configuration file, you have to use the following + notation:</p> + <pre> +Selective_Decode_Instruction = {selective_decode,{Module_Name,Decode_Instructions}}. + +Module_Name = atom() + +Decode_Instructions = [Decode_Instruction]+ + +Decode_Instruction = {Selective_Decode_Function_Name,Type_List} + +Selective_Decode_Function_Name = atom() + +Type_List = [Top_Type|Element_List] + +Element_List = Name|List_Selector + +Name = atom() + +List_Selector = [integer()] </pre> + <p>Observe that the instruction must be a valid Erlang term ended + by a dot. + </p> + <p>The <c>Module_Name</c> is the same as the name of the ASN.1 + spec, but without the extension. A <c>Decode_Instruction</c> is + a tuple with your chosen function name and the components from + the top type that leads to the single type you want to + decode. Notice that you have to choose a name of your function + that will not be the same as any of the generated functions. The + first element of the <c>Type_List</c> is the top type of the + encoded message. In the <c>Element_List</c> it is followed by + each of the component names that leads to selected type. Each of + the names in the <c>Element_List</c> must be constructed types + except the last name, which can be any type. + </p> + <p>The List_Selector makes it possible to choose one of the + encoded components in a SEQUENCE OF/ SET OF. It is also possible + to go further in that component and pick a sub type of that to + decode. So in the <c>Type_List</c>: <c>['Window',status,buttonList,[1],number]</c> the + component <c>buttonList</c> has to be a SEQUENCE OF or SET OF type. In + this example component <c>number</c> of the first of the encoded + elements in the SEQUENCE OF <c>buttonList</c> is selected. This apply on + the ASN.1 spec <seealso marker="#Asn1spec">above</seealso>. + </p> + </section> + + <section> + <title>Another Example</title> + <p>In this example we use the same ASN.1 spec as <seealso marker="#Asn1spec">above</seealso>. A valid selective decode + instruction is:</p> + <pre> +{selective_decode, + {'GUI', + [{selected_decode_Window1, + ['Window',status,buttonList, + [1], + number]}, + {selected_decode_Action, + ['Action',handle,number]}, + {selected_decode_Window2, + ['Window', + status, + actions, + possibleActions, + [1], + handle,number]}]}}. + </pre> + <p>The first <c>Decode_Instruction</c>, + <c>{selected_decode_Window1,['Window',status,buttonList,[1],number]}</c> + is commented in the previous section. The instruction + <c>{selected_decode_Action,['Action',handle,number]}</c> picks + the component <c>number</c> in the <c>handle</c> component of the type + <c>Action</c>. If we have the value <c>ValAction = {'Action',17,{'Button',4711,false}}</c> the internal value 4711 + should be picked by <c>selected_decode_Action</c>. In an Erlang + terminal it looks like:</p> + <pre> +ValAction = {'Action',17,{'Button',4711,false}}. +{'Action',17,{'Button',4711,false}} +7> {ok,Bytes}='GUI':encode('Action',ValAction). +... +8> BinBytes = list_to_binary(Bytes). +<<48,18,2,1,17,160,13,172,11,171,9,48,7,128,2,18,103,129,1,0>> +9> 'GUI':selected_decode_Action(BinBytes). +{ok,4711} +10> </pre> + <p>The third instruction, + <c>['Window',status,actions,possibleActions,[1],handle,number]</c>, + which is a little more complicated,</p> + <list type="bulleted"> + <item>starts with type <em>Window</em>. </item> + <item>Picks component <em>status</em> of <c>Window</c> that is + of type <c>Status</c>.</item> + <item>Then takes component <em>actions</em> of type + <c>Status</c>.</item> + <item>Then <em>possibleActions</em> of the internal defined + CHOICE type.</item> + <item>Thereafter it goes into the first component of the + SEQUENCE OF by <em>[1]</em>. That component is of type + <c>Action</c>.</item> + <item>The instruction next picks component + <em>handle</em>.</item> + <item>And finally component <em>number</em> of the type + <c>Button</c>.</item> + </list> + <p>The following figures shows which components are in the + TypeList + <c>['Window',status,actions,possibleActions,[1],handle,number]</c>. And + which part of a message that will be decoded by + selected_decode_Window2. + </p> + <p></p> + <image file="selective_TypeList.gif"> + <icaption>The elements specified in the config file for selective decode of a sub-value in a Window message</icaption> + </image> + <p></p> + <image file="selective_Window2.gif"> + <icaption>Figure symbolizes the bytes of a Window:status message. Only the marked element is decoded when selected_decode_Window2 is called. </icaption> + </image> + <p>With the following example you can examine that both + <c>selected_decode_Window2</c> and + <c>selected_decode_Window1</c> decodes the intended sub-value + of the value <c>Val</c></p> + <pre> +1> Val = {'Window',{status,{'Status',12, + [{'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}], + true, + {possibleActions,[{'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}]}}}} +2> {ok,Bytes}='GUI':encode('Window',Val). +... +3> Bin = list_to_binary(Bytes). +<<161,101,128,1,12,161,32,48,6,128,1,13,129,1,255,48,6,128,1,14,129,1,0,48,6,128,1,15,129,...>> +4> 'GUI':selected_decode_Window1(Bin). +{ok,13} +5> 'GUI':selected_decode_Window2(Bin). +{ok,18} </pre> + <p>Observe that the value feed into the selective decode + functions must be a binary. + </p> + </section> + </section> + + <section> + <title>Performance</title> + <p>To give an indication on the possible performance gain using + the specialized decodes, some measures have been performed. The + relative figures in the outcome between selective, exclusive and + complete decode (the normal case) depends on the structure of + the type, the size of the message and on what level the + selective and exclusive decodes are specified. + </p> + + <section> + <title>ASN.1 Specifications, Messages and Configuration</title> + <p>The specs <seealso marker="#Asn1spec">GUI</seealso> and + <url href="http://www.itu.int/ITU-T/asn1/database/itu-t/h/h248/2002/MEDIA-GATEWAY-CONTROL.html">MEDIA-GATEWAY-CONTROL</url> + was used in the test. + </p> + <p>For the GUI spec the configuration looked like:</p> + <pre> +{selective_decode, + {'GUI', + [{selected_decode_Window1, + ['Window', + status,buttonList, + [1], + number]}, + {selected_decode_Window2, + ['Window', + status, + actions, + possibleActions, + [1], + handle,number]}]}}. + {exclusive_decode, + {'GUI', + [{decode_Window_status_exclusive, + ['Window', + [{status, + [{buttonList,parts}, + {actions,undecoded}]}]]}]}}. + </pre> + <p>The MEDIA-GATEWAY-CONTROL configuration was:</p> + <pre> +{exclusive_decode, + {'MEDIA-GATEWAY-CONTROL', + [{decode_MegacoMessage_exclusive, + ['MegacoMessage', + [{authHeader,undecoded}, + {mess, + [{mId,undecoded}, + {messageBody,undecoded}]}]]}]}}. +{selective_decode, + {'MEDIA-GATEWAY-CONTROL', + [{decode_MegacoMessage_selective, + ['MegacoMessage',mess,version]}]}}. + </pre> + <p>The corresponding values were:</p> + <pre> +{'Window',{status,{'Status',12, + [{'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}, + {'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}, + {'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}], + true, + {possibleActions, + [{'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}]}}}} + + +{'MegacoMessage',asn1_NOVALUE, + {'Message',1, + {ip4Address, + {'IP4Address',[125,125,125,111],55555}}, + {transactions, + [{transactionReply, + {'TransactionReply',50007,asn1_NOVALUE, + {actionReplies, + [{'ActionReply',0,asn1_NOVALUE,asn1_NOVALUE, + [{auditValueReply,{auditResult,{'AuditResult', + {'TerminationID',[],[255,255,255]}, + [{mediaDescriptor, + {'MediaDescriptor',asn1_NOVALUE, + {multiStream, + [{'StreamDescriptor',1, + {'StreamParms', + {'LocalControlDescriptor', + sendRecv, + asn1_NOVALUE, + asn1_NOVALUE, + [{'PropertyParm', + [0,11,0,7], + [[52,48]], + asn1_NOVALUE}]}, + {'LocalRemoteDescriptor', + [[{'PropertyParm', + [0,0,176,1], + [[48]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,8], + [[73,78,32,73,80,52,32,49,50,53,46,49, + 50,53,46,49,50,53,46,49,49,49]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,15], + [[97,117,100,105,111,32,49,49,49,49,32, + 82,84,80,47,65,86,80,32,32,52]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,12], + [[112,116,105,109,101,58,51,48]], + asn1_NOVALUE}]]}, + {'LocalRemoteDescriptor', + [[{'PropertyParm', + [0,0,176,1], + [[48]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,8], + [[73,78,32,73,80,52,32,49,50,52,46,49,50, + 52,46,49,50,52,46,50,50,50]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,15], + [[97,117,100,105,111,32,50,50,50,50,32,82, + 84,80,47,65,86,80,32,32,52]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,12], + [[112,116,105,109,101,58,51,48]], + asn1_NOVALUE}]]}}}]}}}, + {packagesDescriptor, + [{'PackagesItem',[0,11],1}, + {'PackagesItem',[0,11],1}]}, + {statisticsDescriptor, + [{'StatisticsParameter',[0,12,0,4],[[49,50,48,48]]}, + {'StatisticsParameter',[0,11,0,2],[[54,50,51,48,48]]}, + {'StatisticsParameter',[0,12,0,5],[[55,48,48]]}, + {'StatisticsParameter',[0,11,0,3],[[52,53,49,48,48]]}, + {'StatisticsParameter',[0,12,0,6],[[48,46,50]]}, + {'StatisticsParameter',[0,12,0,7],[[50,48]]}, + {'StatisticsParameter',[0,12,0,8],[[52,48]]}]}]}}}]}]}}}]}}} + </pre> + <p>The size of the encoded values was 458 bytes for GUI and 464 + bytes for MEDIA-GATEWAY-CONTROL. + </p> + </section> + + <section> + <title>Results</title> + <p>The ASN.1 specs in the test are compiled with the options + <c>ber_bin, optimize, driver</c> and <c>asn1config</c>. If the + <c>driver</c> option had been omitted there should have been + higher values for <c>decode</c> and <c>decode_part</c>. + </p> + <p>The test program runs 10000 decodes on the value, resulting + in a printout with the elapsed time in microseconds for the + total number of decodes. + </p> + <table> + <row> + <cell align="left" valign="top"><em>Function</em></cell> + <cell align="left" valign="top"><em>Time</em>(microseconds)</cell> + <cell align="left" valign="top"><em>Kind of Decode</em></cell> + <cell align="left" valign="top"><em>ASN.1 spec</em></cell> + <cell align="left" valign="top"><em>% of time vs. complete decode</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_MegacoMessage_selective/1</c></cell> + <cell align="left" valign="middle"><c>374045</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>8.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_MegacoMessage_exclusive/1</c></cell> + <cell align="left" valign="middle"><c>621107</c></cell> + <cell align="left" valign="middle"><c>exclusive</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>13.8</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>4507457</c></cell> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selected_decode_Window1/1</c></cell> + <cell align="left" valign="middle"><c>449585</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>7.6</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selected_decode_Window2/1</c></cell> + <cell align="left" valign="middle"><c>890666</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>15.1</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_Window_status_exclusive/1</c></cell> + <cell align="left" valign="middle"><c>1251878</c></cell> + <cell align="left" valign="middle"><c>exclusive</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>21.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>5889197</c></cell> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <tcaption>Results of complete, exclusive and selective decode</tcaption> + </table> + <p>Another interesting question is what the relation is between + a complete decode, an exclusive decode followed by + <c>decode_part</c> of the excluded parts and a selective decode + followed by a complete decode. Some situations may be compared to + this simulation, e.g. inspect a sub-value and later on look at + the entire value. The following table shows figures from this + test. The number of loops and time unit is the same as in the + previous test. + </p> + <table> + <row> + <cell align="left" valign="top"><em>Actions</em></cell> + <cell align="left" valign="top"><em>Function</em> </cell> + <cell align="left" valign="top"><em>Time</em>(microseconds)</cell> + <cell align="left" valign="top"><em>ASN.1 spec</em></cell> + <cell align="left" valign="top"><em>% of time vs. complete decode</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>4507457</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>decode_­MegacoMessage_­selective/1</c></cell> + <cell align="left" valign="middle"><c>4881502</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>108.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>exclusive and decode_part</c></cell> + <cell align="left" valign="middle"><c>decode_­MegacoMessage_­exclusive/1</c></cell> + <cell align="left" valign="middle"><c>5481034</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>112.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>5889197</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>selected_­decode_­Window1/1</c></cell> + <cell align="left" valign="middle"><c>6337636</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>107.6</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>selected_­decode_­Window2/1</c></cell> + <cell align="left" valign="middle"><c>6795319</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>115.4</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>exclusive and decode_part</c></cell> + <cell align="left" valign="middle"><c>decode_­Window_­status_­exclusive/1</c></cell> + <cell align="left" valign="middle"><c>6249200</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>106.1</em></cell> + </row> + <tcaption>Results of complete, exclusive + decode_part and selective + complete decodes</tcaption> + </table> + <p>Other ASN.1 types and values can differ much from these + figures. Therefore it is important that you, in every case where + you intend to use either of these decodes, perform some tests + that shows if you will benefit your purpose. + </p> + </section> + + <section> + <title>Comments</title> + <p>Generally speaking the gain of selective and exclusive decode + in advance of complete decode is greater the bigger value and the + less deep in the structure you have to decode. One should also + prefer selective decode instead of exclusive decode if you are + interested in just one single sub-value.</p> + <p>Another observation is that the exclusive decode followed by + decode_part decodes is very attractive if the parts will be sent + to different servers for decoding or if one in some cases not is + interested in all parts.</p> + <p>The fastest selective decode are when the decoded type is a + primitive type and not so deep in the structure of the top + type. The <c>selected_decode_Window2</c> decodes a big constructed + value, which explains why this operation is relatively slow.</p> + <p>It may vary from case to case which combination of + selective/complete decode or exclusive/part decode is the fastest.</p> + </section> + </section> +</chapter> + |