diff options
Diffstat (limited to 'lib/cosNotification/doc/src/ch_QoS.xml')
| -rw-r--r-- | lib/cosNotification/doc/src/ch_QoS.xml | 252 |
1 files changed, 0 insertions, 252 deletions
diff --git a/lib/cosNotification/doc/src/ch_QoS.xml b/lib/cosNotification/doc/src/ch_QoS.xml deleted file mode 100644 index 7f7a26f69a..0000000000 --- a/lib/cosNotification/doc/src/ch_QoS.xml +++ /dev/null @@ -1,252 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2000</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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> - |