diff options
Diffstat (limited to 'lib/cosNotification/doc/src/ch_QoS.xml')
| -rw-r--r-- | lib/cosNotification/doc/src/ch_QoS.xml | 251 |
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> + |