More Information about IObservable and IEnumerable Interfaces in StreamInsight
This topic contains more information that will help you to understand the support for observable and enumerable event sources and sinks in StreamInsight.
Support for the IObservable and IObserver interfaces in StreamInsight
Overview of the IObservable and IObserver interfaces
The IObservable interface provides the following method:
Method |
Description |
|---|---|
Subscribe |
Creates and returns a subscription that implements the IObserver interface. |
The IObserver interface provides the following methods:
Method |
Description |
|---|---|
OnNext |
Notifies the observer of a new value in the sequence. |
OnError |
Notifies the observer that an exception has occurred and the sequence is terminated. No calls to OnNext, OnCompleted or OnError can follow this call. |
OnCompleted |
Notifies the observer of the end of the sequence. No calls to OnNext, OnCompleted or OnError can follow this call. |
Dispose |
Disposes the subscription. |
Input from an IObservable event source
When you start a query that is bound to an observable input, StreamInsight calls the IObservable.Subscribe method of the event source, a subscription is created, and the event source begins to provide data. The input can report normal termination of its source data by calling IObserver.OnCompleted. Or, the user can stop the input by disposing the subscription.
Exceptions and exception handling
When your StreamInsight query consumes an observable input, you do not call the methods of the IObservable or IObserver interfaces in the code that you write; StreamInsight calls the appropriate methods for you. However the following information will help you to understand when exceptions can occur and how they are handled.
The input adapter maintains a reference to the observable event source that supplies events.
If a call to IObservable.Subscribe raises an exception, the exception will be propagated to the StreamInsight runtime and the query will be aborted.
If a call to IObserver.Dispose raises an exception, the exception will be logged and ignored.
A call to IObserver.OnCompleted causes the input adapter to signal that it has stopped. Any calls to IObserver methods that follow this call are treated as errors and might throw exceptions.
Exceptions that occur on calls to IObserver.OnNext cause the query to be aborted and the subscription to be disposed. Any calls to IObserver methods that follow this call are treated as errors and might throw exceptions. An exception on a call to OnNext can be caused by:
A null event.
A CTI violation.
An exception thrown from a selector expression.
A call to IObserver.OnNext blocks while the input adapter’s stream is full and no event can be enqueued.
A call to IObserver OnError causes the query to be aborted. Any calls to IObserver methods that follow this call are treated as errors and might throw exceptions.
Output to an IObservable event sink
When the observer creates a subscription by calling the Subscribe method of an IObservable output, an instance of a query is created and started, and the transient output begins to provide data. A query instance exists for each subscription, and exists only while the consumer exists. StreamInsight can report normal termination of a query by calling IObserver.OnCompleted. Or, the user can stop and implicitly delete the query by disposing the subscription. Conversely, a transient query is not deleted until the corresponding subscription is disposed.
Exceptions and exception handling
When you consume the output of a StreamInsight query through the IObservable and IObserver interfaces, the code that you write in the consumer calls the methods of these interfaces directly. The following information will help you to understand when exceptions can occur and how they are handled.
When a stream is converted to an IObservable output, this observable instance maintains a reference to the original stream. After this, observers can subscribe to receive data.
A call to IObservable.Subscribe causes a query to be created and started, and to begin supplying events to the observer. Subscribe can raise an exception when any of the following conditions are true:
The server is not an embedded server.
The query cannot be created.
The query cannot be started.
A call to IObserver.Dispose causes the query to be stopped and then deleted. The implementation ensures that the following statements are true:
After the call to Dispose returns, no further calls to IObserver methods will be made.
The underlying query will be stopped and deleted as soon as possible, but not necessarily before the call to Dispose returns.
A call to Dispose from an IObserver method will not cause a deadlock.
IObserver.OnError is called when the query is aborted. The implementation provides an exception that contains at least textual information about the failure. After a call to OnError, no further calls to IObserver methods will be made. OnError can be called when any of the following conditions are true:
An adapter raises an exception.
An operator raises an exception.
IObserver.OnCompleted is called when the query has finished processing output. After a call to OnCompleted, no further calls to IObserver methods will be made. OnCompleted can be called when any of the following conditions are true:
The output adapter receives a CTI of plus infinity.
The query is suspended because all events have been consumed.
If calls by StreamInsight into IObserver methods (which are calls made into user code) raise an exception, this will cause the query to be aborted. If the query was already in the process of being aborted, this exception will be ignored.
If a selector expression raises an exception, this causes the query to be aborted.
Support for the IEnumerable interface in StreamInsight
Overview of the IEnumerable interface
The IEnumerable interface provides the following method:
Method |
Description |
|---|---|
GetEnumerator |
Creates and returns an enumerator that implements the IEnumerator interface. |
The IEnumerator interface provides the following methods:
Method |
Description |
|---|---|
Current |
Gets the current element. |
MoveNext |
Advances the enumerator to the next element. |
Reset |
Sets the enumerator to its initial position, which is before the first element. No calls to other IEnumerator methods can follow this call. |
Dispose |
Disposes the enumerator. |
Input from an IEnumerable event source
When you start a query that is bound to a transient input, StreamInsight calls the IEnumerable.GetEnumerator method of the event source and obtains an enumerator. Then the event source begins to provide data by calling IEnumerator.MoveNext and IEnumerator.Current in a loop, as long as the input stream is not empty. The input can report normal termination of its source data by returning false when StreamInsight calls MoveNext. Or, the user can stop the input by disposing the enumerator.
Exceptions and exception handling
When your StreamInsight query consumes an enumerable input, you do not call the methods of the IEnumerable or IEnumerator interfaces in the code that you write; StreamInsight calls the appropriate methods for you. However the following information will help you to understand when exceptions can occur and how they are handled.
The input adapter maintains a reference to enumerable event source from which events will be pulled. The input adapter calls into the event source on its own thread to get data.
If a call to IEnumerable.GetEnumerator, or to IEnumerator.Current, IEnumerator.MoveNext, or IEnumerator.Dispose raises an exception, this causes the query to be aborted.
If a selector expression raises an exception, this causes the query to be aborted.
Output to an IEnumerable event sink
When the consumer obtains an enumerator by calling the GetEnumerator method of an IEnumerable output, an instance of a query is created and started, and the transient output begins to provide data. A query instance exists for each enumerator, and exists only while the consumer exists. StreamInsight can report normal termination of a query by returning false when the consumer calls IEnumerator.MoveNext. Or, the user can stop and implicitly delete the query by disposing the enumerator. Conversely, a transient query is not deleted until the corresponding enumerator is disposed.
Exceptions and exception handling
When you consume the output of a StreamInsight query through the IEnumerable and IEnumerator interfaces, the code that you write in the consumer calls the methods of these interfaces directly. The following information will help you to understand when exceptions can occur and how they are handled.
When a stream is converted to an IEnumerable output, this enumerable instance maintains a reference to the original stream. Consumers call the methods of IEnumerable and IEnumerator to pull data.
A call to IEnumerable.GetEnumerator causes a query to be created with an output adapter that will supply values to the external source. GetEnumerator can raise an exception when any of the following conditions are true:
The server is not an embedded server.
The query cannot be created.
The query cannot be started (for example, due to missing adapters).
A call to IEnumerator.Dispose causes the query to be stopped and then deleted. The implementation ensures that after the call to Dispose returns, no further calls to IEnumerator methods will be made. Dispose can raise an exception when any of the following conditions are true:
The query cannot be stopped.
The query cannot be deleted.
A call to the Current method can raise an exception if MoveNext has not been called at least once.
A call to MoveNext:
Does not raise any exceptions.
Returns true as long as there is data to provide.
Returns false when the query has stopped or been aborted.
Blocks while no output data is available to provide.