C# Class RabbitMQ.Client.MessagePatterns.Subscription

Manages a subscription to a queue or exchange.

This convenience class abstracts away from much of the detail involved in receiving messages from a queue or an exchange.

Once created, the Subscription consumes from a queue (using a QueueingBasicConsumer). Received deliveries can be retrieved by calling Next(), or by using the Subscription as an IEnumerator in, for example, a foreach loop.

Note that if the "noAck" option is enabled (which it is by default), then received deliveries are automatically acked within the server before they are even transmitted across the network to us. Calling Ack() on received events will always do the right thing: if "noAck" is enabled, nothing is done on an Ack() call, and if "noAck" is disabled, IModel.BasicAck() is called with the correct parameters.

Inheritance: IEnumerable, IEnumerator, IDisposable

Show file Open project: rabbitmq/rabbitmq-dotnet-client Class Usage Examples

Protected Properties

Property	Type	Description
m_consumer	RabbitMQ.Client.Events.EventingBasicConsumer
m_eventLock	object

Private Properties

Property	Type	Description
HandleConsumerCancelled	void
IDisposable	void
IEnumerable	IEnumerator
IEnumerator	bool
IEnumerator	void
QueueAdd	void

Public Methods

Method	Description
Ack ( ) : void	If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.
Ack ( RabbitMQ.Client.Events.BasicDeliverEventArgs evt ) : void	If we are not in "autoAck" mode, calls IModel.BasicAck with the delivery-tag from evt; otherwise, sends nothing to the server. if evt is the same as LatestEvent by pointer comparison, sets LatestEvent to null. Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour
Close ( ) : void	Closes this Subscription, cancelling the consumer record in the server.
Nack ( RabbitMQ.Client.Events.BasicDeliverEventArgs evt, bool multiple, bool requeue ) : void	If we are not in "autoAck" mode, calls IModel.BasicNack with the delivery-tag from evt; otherwise, sends nothing to the server. if evt is the same as LatestEvent by pointer comparison, sets LatestEvent to null. Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour
Nack ( bool requeue ) : void	If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, false, requeue). Causes LatestEvent to become null.
Nack ( bool multiple, bool requeue ) : void	If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, multiple, requeue). Causes LatestEvent to become null.
Next ( ) : RabbitMQ.Client.Events.BasicDeliverEventArgs	Retrieves the next incoming delivery in our subscription queue. Returns null when the end of the stream is reached and on every subsequent call. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection. Updates LatestEvent to the value returned. Does not acknowledge any deliveries at all (but in "autoAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).
Next ( int millisecondsTimeout, RabbitMQ.Client.Events.BasicDeliverEventArgs &result ) : bool	Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds. Returns false only if the timeout expires before either a delivery appears or the end-of-stream is reached. If false is returned, the out parameter "result" is set to null, but LatestEvent is not updated. Returns true to indicate a delivery or the end-of-stream. If a delivery is already waiting in the queue, or one arrives before the timeout expires, it is removed from the queue and placed in the "result" out parameter. If the end-of-stream is detected before the timeout expires, "result" is set to null. Whenever this method returns true, it updates LatestEvent to the value placed in "result" before returning. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection. This method does not acknowledge any deliveries at all (but in "autoAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us). A timeout of -1 (i.e. System.Threading.Timeout.Infinite) will be interpreted as a command to wait for an indefinitely long period of time for an item or the end of the stream to become available. Usage of such a timeout is equivalent to calling Next() with no arguments (modulo predictable method signature differences).
NextAsync ( ) : Task
Subscription ( IModel model, string queueName ) : System	Creates a new Subscription in "autoAck" mode, consuming from a named queue.
Subscription ( IModel model, string queueName, bool autoAck ) : System	Creates a new Subscription, with full control over both "autoAck" mode and the name of the queue.
Subscription ( IModel model, string queueName, bool autoAck, string consumerTag ) : System	Creates a new Subscription, with full control over both "autoAck" mode, the name of the queue, and the consumer tag.

Protected Methods

Method	Description
MutateLatestEvent ( RabbitMQ.Client.Events.BasicDeliverEventArgs value ) : void

Private Methods

Method	Description
HandleConsumerCancelled ( object sender, RabbitMQ.Client.Events.ConsumerEventArgs e ) : void
IDisposable ( ) : void	Implementation of the IDisposable interface, permitting Subscription to be used in using statements. Simply calls Close().
IEnumerable ( ) : IEnumerator	Implementation of the IEnumerable interface, for permitting Subscription to be used in foreach loops.
IEnumerator ( ) : bool	Implementation of the IEnumerator interface, for permitting Subscription to be used in foreach loops. Does not acknowledge any deliveries at all. Ack() must be called explicitly on received deliveries.
IEnumerator ( ) : void	Dummy implementation of the IEnumerator interface, for permitting Subscription to be used in foreach loops; Reset()ting a Subscription doesn't make sense, so this method always throws InvalidOperationException.
QueueAdd ( RabbitMQ.Client.Events.BasicDeliverEventArgs args ) : void

Method Details

Ack() public method

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

public Ack ( ) : void
return	void

Ack() public method

If we are not in "autoAck" mode, calls IModel.BasicAck with the delivery-tag from evt; otherwise, sends nothing to the server. if evt is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour

public Ack ( RabbitMQ.Client.Events.BasicDeliverEventArgs evt ) : void
evt	RabbitMQ.Client.Events.BasicDeliverEventArgs
return	void

Close() public method

Closes this Subscription, cancelling the consumer record in the server.

public Close ( ) : void
return	void

MutateLatestEvent() protected method

protected MutateLatestEvent ( RabbitMQ.Client.Events.BasicDeliverEventArgs value ) : void
value	RabbitMQ.Client.Events.BasicDeliverEventArgs
return	void

Nack() public method

If we are not in "autoAck" mode, calls IModel.BasicNack with the delivery-tag from evt; otherwise, sends nothing to the server. if evt is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour

public Nack ( RabbitMQ.Client.Events.BasicDeliverEventArgs evt, bool multiple, bool requeue ) : void
evt	RabbitMQ.Client.Events.BasicDeliverEventArgs
multiple	bool
requeue	bool
return	void

Nack() public method

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, false, requeue). Causes LatestEvent to become null.

public Nack ( bool requeue ) : void
requeue	bool
return	void

Nack() public method

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, multiple, requeue). Causes LatestEvent to become null.

public Nack ( bool multiple, bool requeue ) : void
multiple	bool
requeue	bool
return	void

Next() public method

Retrieves the next incoming delivery in our subscription queue.

Returns null when the end of the stream is reached and on every subsequent call. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

Updates LatestEvent to the value returned.

Does not acknowledge any deliveries at all (but in "autoAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

public Next ( ) : RabbitMQ.Client.Events.BasicDeliverEventArgs
return	RabbitMQ.Client.Events.BasicDeliverEventArgs

Next() public method

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

Returns false only if the timeout expires before either a delivery appears or the end-of-stream is reached. If false is returned, the out parameter "result" is set to null, but LatestEvent is not updated.

Returns true to indicate a delivery or the end-of-stream.

If a delivery is already waiting in the queue, or one arrives before the timeout expires, it is removed from the queue and placed in the "result" out parameter. If the end-of-stream is detected before the timeout expires, "result" is set to null.

Whenever this method returns true, it updates LatestEvent to the value placed in "result" before returning.

End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

This method does not acknowledge any deliveries at all (but in "autoAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

A timeout of -1 (i.e. System.Threading.Timeout.Infinite) will be interpreted as a command to wait for an indefinitely long period of time for an item or the end of the stream to become available. Usage of such a timeout is equivalent to calling Next() with no arguments (modulo predictable method signature differences).

public Next ( int millisecondsTimeout, RabbitMQ.Client.Events.BasicDeliverEventArgs &result ) : bool
millisecondsTimeout	int
result	RabbitMQ.Client.Events.BasicDeliverEventArgs
return	bool

NextAsync() public method

public NextAsync ( ) : Task
return	Task

Subscription() public method

Creates a new Subscription in "autoAck" mode, consuming from a named queue.

public Subscription ( IModel model, string queueName ) : System
model	IModel
queueName	string
return	System

Subscription() public method

Creates a new Subscription, with full control over both "autoAck" mode and the name of the queue.

public Subscription ( IModel model, string queueName, bool autoAck ) : System
model	IModel
queueName	string
autoAck	bool
return	System

Subscription() public method

Creates a new Subscription, with full control over both "autoAck" mode, the name of the queue, and the consumer tag.

public Subscription ( IModel model, string queueName, bool autoAck, string consumerTag ) : System
model	IModel
queueName	string
autoAck	bool
consumerTag	string
return	System

Property Details

m_consumer protected property

protected EventingBasicConsumer,RabbitMQ.Client.Events m_consumer
return	RabbitMQ.Client.Events.EventingBasicConsumer

m_eventLock protected property

protected object m_eventLock
return	object