Skip to content
Ice Docs

IceStorm Concepts

5 min read

5 min read

5 min read

5 min read

5 min read

5 min read

5 min read

5 min read

5 min read

IceStorm distributes events from publishers to subscribers through named topics: a publisher publishes an event on a topic, and IceStorm forwards it to the topic's subscribers.

A topic is a named channel. An IceStorm service hosts any number of topics, and each topic can have multiple publishers and subscribers.

An event is a call to an operation of a Slice interface that the publishers and subscribers of a topic agree on: the publisher makes the call once, and IceStorm makes the same call on each subscriber. For example, the sensors of the weather application publish their readings by calling report on the WeatherStation interface, and each weather station receives the same report call:

Slice
module ClearSky
{
    class AtmosphericConditions
    {
        double temperature;
        double humidity;
    }


    interface WeatherStation
    {
        void report(string sensorId, string timeStamp, AtmosphericConditions reading);
    }
}

A publisher calls getPublisher on the topic to obtain a proxy to the topic's publisher object, and publishes an event by invoking an operation on this proxy.

A subscriber is an Ice object that implements the topic's interface. An application, often the server that hosts this object, subscribes it to the topic by calling subscribeAndGetPublisher with a proxy to the object. IceStorm then makes each event's call on the subscriber.

An event is unidirectional: its operation returns void, has no out-parameters and declares no user exceptions, so a publisher receives no results from the subscribers.

A publisher can publish events with oneway or twoway invocations. A twoway invocation returns once IceStorm has accepted the event for forwarding.

Each subscriber can set quality of service (QoS) parameters that control the delivery of its events, including their ordering and what happens when a delivery fails.

By default, IceStorm removes a subscriber when a delivery to it fails. The retryCount parameter keeps the subscription through a number of consecutive transient failures; the subscriber does not receive the events published while it is unreachable. See Retry Count QoS for IceStorm.

By default, IceStorm stores its topics, links and subscriptions in a database, so they survive a restart of the service. IceStorm queues events in memory only while forwarding them: a subscriber receives only the events published while it is subscribed, and IceStorm discards each event once it has forwarded it to the current subscribers.

In transient mode, IceStorm uses no database: its topics, links and subscriptions last only until the service stops, and replication is unavailable.

Federation links topics, so that the events published on one topic also reach the subscribers of other topics. A link goes from a source topic to a target topic, and has a cost that can restrict which events IceStorm forwards on it.

A topic that receives an event over a link delivers the event to its subscribers but does not forward it on its own links: events propagate at most one hop from the originating topic.

The following figure presents an example of topic federation. Topic T1 has links to T2 and T3, as indicated by the dotted arrows. Solid arrows show publishers publishing events on topics and topics delivering events to subscribers. The subscribers S1 and S2 receive all events published on T2, as well as those published on T1. Subscriber S3 receives events only from T1, and S4 receives events from both T3 and T1.

Topic federation in IceStorm Publisher P1 publishes to T2, P2 to T1, and P3 to T3. T1 has links to T2 and T3 and sends to subscriber S3. T2 sends to S1 and S2; T3 sends to S4. Dotted arrows show topic links; solid arrows show event delivery. Event delivery Topic link IceStorm P1 P2 P3 T1 T2 T3 S1 S2 S3 S4

A subscriber of both T2 and T3 receives each event published on T1 twice, once through each link.

A replicated IceStorm service keeps topics and subscriptions available when a replica fails. The replicas share their topics, links and subscriptions, and each replica forwards the events published to it: an event that a replica has accepted is lost if this replica fails before forwarding it.