Module amqp_channel

This module encapsulates the client's view of an AMQP channel.

Behaviours: gen_server.

Description

This module encapsulates the client's view of an AMQP channel. Each server side channel is represented by an amqp_channel process on the client side. Channel processes are created using the amqp_connection module. Channel processes are supervised under amqp_client's supervision tree.

In case of a failure or an AMQP error, the channel process exits with a meaningful exit reason:

Cause Exit reason
Any reason, where Code would have been 200 otherwise
  normal
User application calls amqp_channel:close/3
  close_reason(app_initiated_close)
Server closes channel (soft error)
  close_reason(server_initiated_close)
Server misbehaved (did not follow protocol)
  close_reason(server_misbehaved)
Connection is closing (causing all channels to cleanup and close)
  {shutdown, {connection_closing, amqp_reason(atom())}}
Other error (various error reasons, causing more detailed logging)

See type definitions below.

Data Types

amqp_method()

abstract datatype: amqp_method()

This abstract datatype represents the set of methods that comprise the AMQP execution model. As indicated in the overview, the attributes of each method in the execution model are described in the protocol documentation. The Erlang record definitions are autogenerated from a parseable version of the specification. Most fields in the generated records have sensible default values that you need not worry in the case of a simple usage of the client library.

amqp_msg()

amqp_msg() = #amqp_msg{}

This is the content encapsulated in content-bearing AMQP methods. It contains the following fields:

amqp_reason()

amqp_reason(Type) = {Type, Code, Text}

close_reason()

close_reason(Type) = {shutdown, amqp_reason(Type)}

Function Index

call/2This is equivalent to amqp_channel:call(Channel, Method, none).
call/3This sends an AMQP method on the channel.
call_consumer/2This causes the channel to invoke Consumer:handle_call/2, where Consumer is the amqp_gen_consumer implementation registered with the channel.
cast/2This is equivalent to amqp_channel:cast(Channel, Method, none).
cast/3This function is the same as call/3, except that it returns immediately with the atom 'ok', without blocking the caller process.
cast_flow/3Like cast/3, with flow control.
close/1Closes the channel, invokes close(Channel, 200, <<"Goodbye">>).
close/3Closes the channel, allowing the caller to supply a reply code and text.
enable_delivery_flow_control/1
next_publish_seqno/1When in confirm mode, returns the sequence number of the next message to be published.
notify_received/1
register_confirm_handler/2This registers a handler to deal with confirm-related messages.
register_flow_handler/2This registers a handler to deal with channel flow notifications.
register_return_handler/2This registers a handler to deal with returned messages.
set_writer/2
subscribe/3Subscribe the given pid to a queue using the specified basic.consume method.
unregister_confirm_handler/1Removes the confirm handler, if it exists.
unregister_flow_handler/1Removes the flow handler, if it exists.
unregister_return_handler/1Removes the return handler, if it exists.
wait_for_confirms/1Wait until all messages published since the last call have been either ack'd or nack'd by the broker.
wait_for_confirms/2Wait until all messages published since the last call have been either ack'd or nack'd by the broker or the timeout expires.
wait_for_confirms_or_die/1Behaves the same as wait_for_confirms/1, but if a nack is received, the calling process is immediately sent an exit(nack_received).
wait_for_confirms_or_die/2Behaves the same as wait_for_confirms/1, but if a nack is received, the calling process is immediately sent an exit(nack_received).

Function Details

call/2

call(Channel, Method) -> Result

This is equivalent to amqp_channel:call(Channel, Method, none).

call/3

call(Channel, Method, Content) -> Result

This sends an AMQP method on the channel. For content bearing methods, Content has to be an amqp_msg(), whereas for non-content bearing methods, it needs to be the atom 'none'.
In the case of synchronous methods, this function blocks until the corresponding reply comes back from the server and returns it. In the case of asynchronous methods, the function blocks until the method gets sent on the wire and returns the atom 'ok' on success.
This will return the atom 'blocked' if the server has throttled the client for flow control reasons. This will return the atom 'closing' if the channel is in the process of shutting down.
Note that for asynchronous methods, the synchronicity implied by 'call' only means that the client has transmitted the method to the broker. It does not necessarily imply that the broker has accepted responsibility for the message.

call_consumer/2

call_consumer(Channel, Msg) -> ok

This causes the channel to invoke Consumer:handle_call/2, where Consumer is the amqp_gen_consumer implementation registered with the channel.

cast/2

cast(Channel, Method) -> ok

This is equivalent to amqp_channel:cast(Channel, Method, none).

cast/3

cast(Channel, Method, Content) -> ok

This function is the same as call/3, except that it returns immediately with the atom 'ok', without blocking the caller process. This function is not recommended with synchronous methods, since there is no way to verify that the server has received the method.

cast_flow/3

cast_flow(Channel, Method, Content) -> ok

Like cast/3, with flow control.

close/1

close(Channel) -> ok | closing

Closes the channel, invokes close(Channel, 200, <<"Goodbye">>).

close/3

close(Channel, Code, Text) -> ok | closing

Closes the channel, allowing the caller to supply a reply code and text. If the channel is already closing, the atom 'closing' is returned.

enable_delivery_flow_control/1

enable_delivery_flow_control(Pid) -> any()

next_publish_seqno/1

next_publish_seqno(Channel) -> integer()

When in confirm mode, returns the sequence number of the next message to be published.

notify_received/1

notify_received(X1) -> any()

register_confirm_handler/2

register_confirm_handler(Channel, ConfirmHandler) -> ok

This registers a handler to deal with confirm-related messages. The registered process will receive #basic.ack{} and #basic.nack{} commands.

register_flow_handler/2

register_flow_handler(Channel, FlowHandler) -> ok

This registers a handler to deal with channel flow notifications. The registered process will receive #channel.flow{} records.

register_return_handler/2

register_return_handler(Channel, ReturnHandler) -> ok

This registers a handler to deal with returned messages. The registered process will receive #basic.return{} records.

set_writer/2

set_writer(Pid, Writer) -> any()

subscribe/3

subscribe(Channel, BasicConsume, Subscriber) -> ok

Subscribe the given pid to a queue using the specified basic.consume method.

unregister_confirm_handler/1

unregister_confirm_handler(Channel) -> ok

Removes the confirm handler, if it exists. Does nothing if there is no such handler.

unregister_flow_handler/1

unregister_flow_handler(Channel) -> ok

Removes the flow handler, if it exists. Does nothing if there is no such handler.

unregister_return_handler/1

unregister_return_handler(Channel) -> ok

Removes the return handler, if it exists. Does nothing if there is no such handler.

wait_for_confirms/1

wait_for_confirms(Channel) -> boolean() | timeout

Wait until all messages published since the last call have been either ack'd or nack'd by the broker. Note, when called on a non-Confirm channel, waitForConfirms returns an error.

wait_for_confirms/2

wait_for_confirms(Channel, Timeout) -> boolean() | timeout

Wait until all messages published since the last call have been either ack'd or nack'd by the broker or the timeout expires. Note, when called on a non-Confirm channel, waitForConfirms throws an exception.

wait_for_confirms_or_die/1

wait_for_confirms_or_die(Channel) -> true

Behaves the same as wait_for_confirms/1, but if a nack is received, the calling process is immediately sent an exit(nack_received).

wait_for_confirms_or_die/2

wait_for_confirms_or_die(Channel, Timeout) -> true

Behaves the same as wait_for_confirms/1, but if a nack is received, the calling process is immediately sent an exit(nack_received). If the timeout expires, the calling process is sent an exit(timeout).


Generated by EDoc, Jan 6 2015, 16:25:02.