From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/cosNotification/doc/src/ch_QoS.xml | 251 +++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 lib/cosNotification/doc/src/ch_QoS.xml (limited to 'lib/cosNotification/doc/src/ch_QoS.xml') 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 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Quality Of Service and Admin Properties + + + 2000-05-29 + + ch_QoS.xml +
+ +
+ Quality Of Service and Admin Properties +

This chapter explains the allowed properties for + CosNotification_QoSAdmin and + CosNotification_AdminPropertiesAdmin. +

+ +
+ Quality Of Service +

The cosNotification application supports the following QoS settings:

+ + + QoS + Range + Default + + + EventReliability + BestEffort/Persistent + BestEffort + + + ConnectionReliability + BestEffort/Persistent + BestEffort + + + Priority + +/-32767 + 0 + + + OrderPolicy + Any-, Fifo-, Priority- and Deadline-Order + PriorityOrder + + + DiscardPolicy + RejectNewEvents, Any-, Fifo-, Lifo-, Priority- and Deadline-Order + RejectNewEvents + + + MaximumBatchSize + long() > 0 + 1 + + + PacingInterval + TimeBase::TimeT (see cosTime) + 0 + + + StartTimeSupported + boolean + false + + + StopTimeSupported + boolean + false + + + MaxEventsPerConsumer + long() > 0 + 100 + + + Timeout + TimeBase::TimeT (see cosTime) + No timeout + + Table 1: Supported QoS Settings +
+

+

+

+

+

Comments on the table 'Supported QoS Settings':

+ + EventReliability + 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 max_events, + interval_events and timeout_events determine + the behavior of this setting. + ConnectionReliability + If this QoS is set to BestEffort and a client object returns anything + other than ok to its associated Proxy, the Proxy will discard + all events and terminate. Using Persistent and anything other than ok + 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 OBJECT_NOT_EXIST, + NO_PERMISSION or CosEventComm_Disconnected is thrown, + the associated object will terminate even if this parameter is + set to Persistent. + Priority + 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. + OrderPolicy + 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. + DiscardPolicy + 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. + MaximumBatchSize + 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. + PacingInterval + 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. + StartTimeSupported + If set to true events which contains the QoS Property StartTime + (TimeBase::UtcT - absolute time) will not be delivered until the + StartTime value have been exceeded. See also the cosTime application. + StopTimeSupported + If set to true, events which contain the QoS Properties StopTime + (TimeBase::UtcT - absolute time) or Timeout (TimeBase::TimeT - + relative time) will be discarded if the object has not been able to + deliver the event in time. See also the cosTime application. + MaxEventsPerConsumer + The maximum number of events the associated object may store before discarding + events in the way described by the DiscardPolicy. + Timeout + If this QoS property is not included in the event, and the Property + StopTimeSupported equals true, this setting will be applied + if events cannot be delivered within its time limit. + + +

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 ConnectioReliability + may never be updated during run-time since it may cause deadlock. Run-time, in this case, + means activating the Channel by sending the first event.

+ +
+ +
+ Setting Quality Of Service +

Assume we have a Consumer Admin object which we want to change + the current Quality of Service. Typical usage:

+ +QoSPersistent = + [#'CosNotification_Property' + {name='CosNotification':'ConnectionReliability'(), + value=any:create(orber_tc:short(), + 'CosNotification':'Persistent'())}], +'CosNotification_QoSAdmin':set_qos(Ch, QoSPersistent), + +

If it is not possible to set the requested QoS the UnsupportedQoS + exception is raised, which includes a sequence of PropertyError's + describing which QoS, possible range and why is not allowed. The error + codes are:

+ + UNSUPPORTED_PROPERTY - QoS not supported for this type of target object. + UNAVAILABLE_PROPERTY - due to current QoS settings the given property + is not allowed. + UNSUPPORTED_VALUE - property value out of range; valid range is returned. + UNAVAILABLE_VALUE - due to current QoS settings the given value is + not allowed; valid range is returned. + BAD_PROPERTY - unrecognized property. + BAD_TYPE - type of supplied property is incorrect. + BAD_VALUE - illegal value. + +

The CosNotification_QoSAdmin interface also supports an operation + called validate_qos/2. 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.

+
+ +
+ Admin Properties +

The cosNotification application supports the following Admin Properties:

+ + + Property + Range + Default + + + MaxQueueLength + 0 + 0 + + + MaxConsumers + long() >= 0 + 0 + + + MaxSuppliers + long() >= 0 + 0 + + Table 2: Supported Admin Properties +
+

According to the OMG specification the default values for Admin Properties + is supposed to be 0, which means that no limit applies to these + properties.

+ +

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 MaxQueueLength have no effect since + we cannot discard events accordingly to the Quality of Service Property + DiscardPolicy.

+ +
+
+ + -- cgit v1.2.3