The nova.openstack.common.rpc.common Module

exception ClientException

Bases: exceptions.Exception

This encapsulates some actual exception that is expected to be hit by an RPC proxy object. Merely instantiating it records the current exception information, which will be passed back to the RPC client without exceptional logging.

class CommonRpcContext(**kwargs)

Bases: object

deepcopy()

elevated(read_deleted=None, overwrite=False)

Return a version of this context with admin flag set.

classmethod from_dict(values)

to_dict()

update_store()

class Connection

Bases: object

A connection, returned by rpc.create_connection().

This class represents a connection to the message bus used for rpc. An instance of this class should never be created by users of the rpc API. Use rpc.create_connection() instead.

close()

Close the connection.

This method must be called when the connection will no longer be used. It will ensure that any resources associated with the connection, such as a network connection, and cleaned up.

consume_in_thread()

Spawn a thread to handle incoming messages.

Spawn a thread that will be responsible for handling all incoming messages for consumers that were set up on this connection.

Message dispatching inside of this is expected to be implemented in a non-blocking manner. An example implementation would be having this thread pull messages in for all of the consumers, but utilize a thread pool for dispatching the messages to the proxy objects.

create_consumer(topic, proxy, fanout=False)

Create a consumer on this connection.

A consumer is associated with a message queue on the backend message bus. The consumer will read messages from the queue, unpack them, and dispatch them to the proxy object. The contents of the message pulled off of the queue will determine which method gets called on the proxy object.

Parameters:

• topic – This is a name associated with what to consume from. Multiple instances of a service may consume from the same topic. For example, all instances of nova-compute consume from a queue called “compute”. In that case, the messages will get distributed amongst the consumers in a round-robin fashion if fanout=False. If fanout=True, every consumer associated with this topic will get a copy of every message.
• proxy – The object that will handle all incoming messages.
• fanout – Whether or not this is a fanout topic. See the documentation for the topic parameter for some additional comments on this.

create_worker(topic, proxy, pool_name)

Create a worker on this connection.

A worker is like a regular consumer of messages directed to a topic, except that it is part of a set of such consumers (the “pool”) which may run in parallel. Every pool of workers will receive a given message, but only one worker in the pool will be asked to process it. Load is distributed across the members of the pool in round-robin fashion.

Parameters:

• topic – This is a name associated with what to consume from. Multiple instances of a service may consume from the same topic.
• proxy – The object that will handle all incoming messages.
• pool_name – String containing the name of the pool of workers

join_consumer_pool(callback, pool_name, topic, exchange_name)

Register as a member of a group of consumers for a given topic from the specified exchange.

Exactly one member of a given pool will receive each message.

A message will be delivered to multiple pools, if more than one is created.

Parameters:

• callback (callable accepting one argument) – Callable to be invoked for each message.
• pool_name (str) – The name of the consumer pool.
• topic (str) – The routing topic for desired messages.
• exchange_name (str) – The name of the message exchange where the client should attach. Defaults to the configured exchange.

exception DuplicateMessageError(message=None, **kwargs)

Bases: nova.openstack.common.rpc.common.RPCException

message = u'Found duplicate message(%(msg_id)s). Skipping it.'

exception InvalidRPCConnectionReuse(message=None, **kwargs)

Bases: nova.openstack.common.rpc.common.RPCException

message = u'Invalid reuse of an RPC connection.'

LOG = <nova.openstack.common.log.ContextAdapter object at 0x41ee650>

RPC Envelope Version.

This version number applies to the top level structure of messages sent out. It does not apply to the message payload, which must be versioned independently. For example, when using rpc APIs, a version number is applied for changes to the API being exposed over rpc. This version number is handled in the rpc proxy and dispatcher modules.

This version number applies to the message envelope that is used in the serialization done inside the rpc layer. See serialize_msg() and deserialize_msg().

The current message format (version 2.0) is very simple. It is:

{

‘oslo.version’: <RPC Envelope Version as a String>, ‘oslo.message’: <Application Message Payload, JSON encoded>

}

Message format version ‘1.0’ is just considered to be the messages we sent without a message envelope.

So, the current message envelope just includes the envelope version. It may eventually contain additional information, such as a signature for the message payload.

We will JSON encode the application message payload. The message envelope, which includes the JSON encoded application message body, will be passed down to the messaging libraries as a dict.

exception RPCException(message=None, **kwargs)

Bases: exceptions.Exception

message = u'An unknown RPC related exception occurred.'

exception RemoteError(exc_type=None, value=None, traceback=None)

Bases: nova.openstack.common.rpc.common.RPCException

Signifies that a remote class has raised an exception.

Contains a string representation of the type of the original exception, the value of the original exception, and the traceback. These are sent to the parent as a joined string so printing the exception contains all of the relevant info.

message = u'Remote error: %(exc_type)s %(value)s\n%(traceback)s.'

exception Timeout(message=None, **kwargs)

Bases: nova.openstack.common.rpc.common.RPCException

Signifies that a timeout has occurred.

This exception is raised if the rpc_response_timeout is reached while waiting for a response from the remote side.

message = u'Timeout while waiting on RPC response.'

exception UnsupportedRpcEnvelopeVersion(message=None, **kwargs)

Bases: nova.openstack.common.rpc.common.RPCException

message = u'Specified RPC envelope version, %(version)s, not supported by this endpoint.'

exception UnsupportedRpcVersion(message=None, **kwargs)

Bases: nova.openstack.common.rpc.common.RPCException

message = u'Specified RPC version, %(version)s, not supported by this endpoint.'

catch_client_exception(exceptions, func, *args, **kwargs)

client_exceptions(*exceptions)

Decorator for manager methods that raise expected exceptions. Marking a Manager method with this decorator allows the declaration of expected exceptions that the RPC layer should not consider fatal, and not log as if they were generated in a real error scenario. Note that this will cause listed exceptions to be wrapped in a ClientException, which is used internally by the RPC layer.

deserialize_msg(msg)

deserialize_remote_exception(conf, data)

serialize_msg(raw_msg, force_envelope=False)

serialize_remote_exception(failure_info, log_failure=True)

Prepares exception data to be sent over rpc.

Failure_info should be a sys.exc_info() tuple.

version_is_compatible(imp_version, version)

Determine whether versions are compatible.

Parameters:

• imp_version – The version implemented
• version – The version requested by an incoming message.