Erlang -- Quality Of Service and Admin Properties

cosNotification

User's Guide

Version 1.2.2

- User's Guide
- Reference Manual
- Release Notes
- PDF
- Top

- Expand All
- Contract All

### Chapters

- The cosNotification Application
  - Top of chapter
  - Content Overview
  - Brief Description of the User's Guide
- Introduction to cosNotification
  - Top of chapter
  - Overview
- Installing cosNotification
  - Top of chapter
  - Installation Process
- The Notification Service Components
  - Top of chapter
  - The Notification Service Components
- Filters and the Constraint Language BNF
  - Top of chapter
  - Filters and the Constraint Language BNF
- Quality Of Service and Admin Properties
  - Top of chapter
  - Quality Of Service and Admin Properties
- cosNotification Examples
  - Top of chapter
  - A Tutorial on How to Create a Simple Service

# 6 Quality Of Service and Admin Properties

### 6.1 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 6.1: 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.

Warning

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 6.2: 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.

Note

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.