aboutsummaryrefslogtreecommitdiffstats
path: root/lib/cosNotification/doc/src/ch_QoS.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/cosNotification/doc/src/ch_QoS.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/cosNotification/doc/src/ch_QoS.xml')
-rw-r--r--lib/cosNotification/doc/src/ch_QoS.xml251
1 files changed, 251 insertions, 0 deletions
diff --git a/lib/cosNotification/doc/src/ch_QoS.xml b/lib/cosNotification/doc/src/ch_QoS.xml
new file mode 100644
index 0000000000..fbc8622a62
--- /dev/null
+++ b/lib/cosNotification/doc/src/ch_QoS.xml
@@ -0,0 +1,251 @@
+<?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>Quality Of Service and Admin Properties</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date>2000-05-29</date>
+ <rev></rev>
+ <file>ch_QoS.xml</file>
+ </header>
+
+ <section>
+ <title>Quality Of Service and Admin Properties</title>
+ <p>This chapter explains the allowed properties for
+ <seealso marker="CosNotification_QoSAdmin">CosNotification_QoSAdmin</seealso> and
+ <seealso marker="CosNotification_AdminPropertiesAdmin">CosNotification_AdminPropertiesAdmin</seealso>.
+ </p>
+
+ <section>
+ <title>Quality Of Service</title>
+ <p>The cosNotification application supports the following QoS settings:</p>
+ <table>
+ <row>
+ <cell align="center" valign="middle"><em>QoS</em></cell>
+ <cell align="center" valign="middle"><em>Range</em></cell>
+ <cell align="center" valign="middle"><em>Default</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">EventReliability</cell>
+ <cell align="left" valign="middle">BestEffort/Persistent</cell>
+ <cell align="left" valign="middle">BestEffort</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ConnectionReliability</cell>
+ <cell align="left" valign="middle">BestEffort/Persistent</cell>
+ <cell align="left" valign="middle">BestEffort</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">Priority</cell>
+ <cell align="left" valign="middle">+/-32767</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">OrderPolicy</cell>
+ <cell align="left" valign="middle">Any-, Fifo-, Priority- and Deadline-Order</cell>
+ <cell align="left" valign="middle">PriorityOrder</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">DiscardPolicy</cell>
+ <cell align="left" valign="middle">RejectNewEvents, Any-, Fifo-, Lifo-, Priority- and Deadline-Order</cell>
+ <cell align="left" valign="middle">RejectNewEvents</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">MaximumBatchSize</cell>
+ <cell align="left" valign="middle">long() > 0</cell>
+ <cell align="left" valign="middle">1</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">PacingInterval</cell>
+ <cell align="left" valign="middle">TimeBase::TimeT (see cosTime)</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">StartTimeSupported</cell>
+ <cell align="left" valign="middle">boolean</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">StopTimeSupported</cell>
+ <cell align="left" valign="middle">boolean</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">MaxEventsPerConsumer</cell>
+ <cell align="left" valign="middle">long() > 0</cell>
+ <cell align="left" valign="middle">100</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">Timeout</cell>
+ <cell align="left" valign="middle">TimeBase::TimeT (see cosTime)</cell>
+ <cell align="left" valign="middle">No timeout</cell>
+ </row>
+ <tcaption>Table 1: Supported QoS Settings</tcaption>
+ </table>
+ <br></br>
+ <br></br>
+ <br></br>
+ <br></br>
+ <p><em>Comments on the table 'Supported QoS Settings':</em></p>
+ <taglist>
+ <tag><em>EventReliability</em></tag>
+ <item>To allow full Persistent EventReliability, every event must
+ be stored in a stable storage which would create a relatively
+ huge overhead. Hence, only lightweight version of the Persistent
+ QoS is supported. The configuration parameters <c>max_events</c>,
+ <c>interval_events</c> and <c>timeout_events</c> determine
+ the behavior of this setting.</item>
+ <tag><em>ConnectionReliability</em></tag>
+ <item>If this QoS is set to BestEffort and a client object returns anything
+ other than <c>ok</c> to its associated Proxy, the Proxy will discard
+ all events and terminate. Using Persistent and anything other than <c>ok</c>
+ is returned, events will be dropped but the proxy will retry later when
+ next delivery is due. A child may not have Persistent while its parent
+ has BestEffort QoS set, e.g., Proxy vs. Admin. If <c>OBJECT_NOT_EXIST</c>,
+ <c>NO_PERMISSION</c> or <c>CosEventComm_Disconnected</c> is thrown,
+ the associated object will terminate even if this parameter is
+ set to Persistent.</item>
+ <tag><em>Priority</em></tag>
+ <item>This QoS will treat all events as if they have the Priority equal to
+ current value, unless the event itself contains a Priority setting,
+ this event will be treated accordingly. Note: for this property to
+ have any effect, the DiscardPolicy and/or OrderPolicy must be set
+ to PriorityOrder.</item>
+ <tag><em>OrderPolicy</em></tag>
+ <item>If set to PriorityOrder, events with the highest Priority will be
+ delivered first. Deadline order will forward events with shortest
+ expiry time first. If two events have the same priority, they will be
+ delivered in FIFO-order.</item>
+ <tag><em>DiscardPolicy</em></tag>
+ <item>If set to PriorityOrder and MaxEventsPerConsumer limit is
+ reached, events
+ with the lowest Priority will be discarded first. Deadline order will
+ discard events with shortest expiry time first.</item>
+ <tag><em>MaximumBatchSize</em></tag>
+ <item>Only valid if the object is supposed to handle a sequence of structured
+ events and determines the largest amount of events that may be passed
+ each time.</item>
+ <tag><em>PacingInterval</em></tag>
+ <item>Determines how long an object will wait before forwarding a structured
+ event sequence of length equal to, or less than MaximumBatchSize.
+ If set to 0, which is the default behavior, no timeout is used and
+ the events are forwarded when the MaximumBatchSize is reached.</item>
+ <tag><em>StartTimeSupported</em></tag>
+ <item>If set to true events which contains the QoS Property <c>StartTime</c>
+ (TimeBase::UtcT - absolute time) will not be delivered until the
+ StartTime value have been exceeded. See also the <c>cosTime</c> application.</item>
+ <tag><em>StopTimeSupported</em></tag>
+ <item>If set to true, events which contain the QoS Properties <c>StopTime</c>
+ (TimeBase::UtcT - absolute time) or <c>Timeout</c> (TimeBase::TimeT -
+ relative time) will be discarded if the object has not been able to
+ deliver the event in time. See also the <c>cosTime</c> application.</item>
+ <tag><em>MaxEventsPerConsumer</em></tag>
+ <item>The maximum number of events the associated object may store before discarding
+ events in the way described by the DiscardPolicy.</item>
+ <tag><em>Timeout</em></tag>
+ <item>If this QoS property is not included in the event, and the Property
+ <c>StopTimeSupported</c> equals true, this setting will be applied
+ if events cannot be delivered within its time limit.</item>
+ </taglist>
+ <warning>
+ <p>Several of the above QoS Properties can be changed during run-time but we strongly advice
+ not to since, if a relatively large amount of events are waiting for delivery, some of the
+ QoS settings would require a total reorder of the events. The QoS property <c>ConnectioReliability</c>
+ may <em>never</em> be updated during run-time since it may cause deadlock. Run-time, in this case,
+ means activating the Channel by sending the first event.</p>
+ </warning>
+ </section>
+
+ <section>
+ <title>Setting Quality Of Service</title>
+ <p>Assume we have a Consumer Admin object which we want to change
+ the current Quality of Service. Typical usage:</p>
+ <code type="none">
+QoSPersistent =
+ [#'CosNotification_Property'
+ {name='CosNotification':'ConnectionReliability'(),
+ value=any:create(orber_tc:short(),
+ 'CosNotification':'Persistent'())}],
+'CosNotification_QoSAdmin':set_qos(Ch, QoSPersistent),
+ </code>
+ <p>If it is not possible to set the requested QoS the <c>UnsupportedQoS</c>
+ exception is raised, which includes a sequence of <c>PropertyError</c>'s
+ describing which QoS, possible range and why is not allowed. The error
+ codes are:</p>
+ <list type="bulleted">
+ <item>UNSUPPORTED_PROPERTY - QoS not supported for this type of target object.</item>
+ <item>UNAVAILABLE_PROPERTY - due to current QoS settings the given property
+ is not allowed.</item>
+ <item>UNSUPPORTED_VALUE - property value out of range; valid range is returned.</item>
+ <item>UNAVAILABLE_VALUE - due to current QoS settings the given value is
+ not allowed; valid range is returned.</item>
+ <item>BAD_PROPERTY - unrecognized property.</item>
+ <item>BAD_TYPE - type of supplied property is incorrect.</item>
+ <item>BAD_VALUE - illegal value.</item>
+ </list>
+ <p>The CosNotification_QoSAdmin interface also supports an operation
+ called <c>validate_qos/2</c>. The purpose of this operations is to check
+ if a QoS setting is supported by the target object and if so, the operation
+ returns additional properties which could be optionally added as well.</p>
+ </section>
+
+ <section>
+ <title>Admin Properties</title>
+ <p>The cosNotification application supports the following Admin Properties:</p>
+ <table>
+ <row>
+ <cell align="center" valign="middle"><em>Property</em></cell>
+ <cell align="center" valign="middle"><em>Range</em></cell>
+ <cell align="center" valign="middle"><em>Default</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">MaxQueueLength</cell>
+ <cell align="left" valign="middle">0</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">MaxConsumers</cell>
+ <cell align="left" valign="middle">long() >= 0</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">MaxSuppliers</cell>
+ <cell align="left" valign="middle">long() >= 0</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <tcaption>Table 2: Supported Admin Properties</tcaption>
+ </table>
+ <p>According to the OMG specification the default values for Admin Properties
+ is supposed to be <c>0</c>, which means that no limit applies to these
+ properties.</p>
+ <note>
+ <p>Admin Properties can only be set on a Channel Object level, i.e.,
+ they will not have an impact on any Admin or Proxy Objects. Currently,
+ setting the Admin Property <c>MaxQueueLength</c> have no effect since
+ we cannot discard events accordingly to the Quality of Service Property
+ <c>DiscardPolicy</c>.</p>
+ </note>
+ </section>
+ </section>
+</chapter>
+