Advocate use of the rpc:// backend over amqp

docs/configuration.rst

@@ -183,10 +183,18 @@ The backend used to store task results (tombstones).
 Disabled by default.
 Can be one of the following:
 
+* rpc
+    Send results back as AMQP messages
+    See :ref:`conf-rpc-result-backend`.
+
 * database
     Use a relational database supported by `SQLAlchemy`_.
     See :ref:`conf-database-result-backend`.
 
+* redis
+    Use `Redis`_ to store the results.
+    See :ref:`conf-redis-result-backend`.
+
 * cache
     Use `memcached`_ to store the results.
     See :ref:`conf-cache-result-backend`.
@@ -195,14 +203,6 @@ Can be one of the following:
     Use `MongoDB`_ to store the results.
     See :ref:`conf-mongodb-result-backend`.
 
-* redis
-    Use `Redis`_ to store the results.
-    See :ref:`conf-redis-result-backend`.
-
-* amqp
-    Send results back as AMQP messages
-    See :ref:`conf-amqp-result-backend`.
-
 * cassandra
     Use `Cassandra`_ to store the results.
     See :ref:`conf-cassandra-result-backend`.
@@ -215,6 +215,10 @@ Can be one of the following:
     Use `Couchbase`_ to store the results.
     See :ref:`conf-couchbase-result-backend`.
 
+* amqp
+    Older AMQP backend (badly) emulating a database-based backend.
+    See :ref:`conf-amqp-result-backend`.
+
 .. warning:
 
     While the AMQP result backend is very efficient, you must make sure
@@ -330,35 +334,12 @@ you to customize the table names:
         'group': 'myapp_groupmeta',
     }
 
-.. _conf-amqp-result-backend:
-
-AMQP backend settings
----------------------
-
-.. note::
-
-    The AMQP backend requires RabbitMQ 1.1.0 or higher to automatically
-    expire results.  If you are running an older version of RabbitmQ
-    you should disable result expiration like this:
-
-        CELERY_TASK_RESULT_EXPIRES = None
-
-.. setting:: CELERY_RESULT_EXCHANGE
-
-CELERY_RESULT_EXCHANGE
-~~~~~~~~~~~~~~~~~~~~~~
-
-Name of the exchange to publish results in.  Default is `celeryresults`.
+.. _conf-rpc-result-backend:
 
-.. setting:: CELERY_RESULT_EXCHANGE_TYPE
-
-CELERY_RESULT_EXCHANGE_TYPE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The exchange type of the result exchange.  Default is to use a `direct`
-exchange.
+RPC backend settings
+--------------------
 
-.. setting:: CELERY_RESULT_PERSISTENT
+.. _conf-amqp-result-backend:
 
 CELERY_RESULT_PERSISTENT
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -372,8 +353,9 @@ Example configuration
 
 .. code-block:: python
 
-    CELERY_RESULT_BACKEND = 'amqp'
-    CELERY_TASK_RESULT_EXPIRES = 18000  # 5 hours.
+    CELERY_RESULT_BACKEND = 'rpc://'
+    CELERY_RESULT_PERSISTENT = False
+
 
 .. _conf-cache-result-backend:
 
@@ -704,6 +686,55 @@ This is a dict supporting the following keys:
 * password
     Password to authenticate to the Couchbase server (optional).
 
+AMQP backend settings
+---------------------
+
+.. admonition:: Do not use in production.
+
+    This is the old AMQP result backend that creates one queue per task,
+    if you want to send results back as message please consider using the
+    RPC backend instead, or if you need the results to be persistent
+    use a result backend designed for that purpose (e.g. Redis, or a database).
+
+.. note::
+
+    The AMQP backend requires RabbitMQ 1.1.0 or higher to automatically
+    expire results.  If you are running an older version of RabbitMQ
+    you should disable result expiration like this:
+
+        CELERY_TASK_RESULT_EXPIRES = None
+
+.. setting:: CELERY_RESULT_EXCHANGE
+
+CELERY_RESULT_EXCHANGE
+~~~~~~~~~~~~~~~~~~~~~~
+
+Name of the exchange to publish results in.  Default is `celeryresults`.
+
+.. setting:: CELERY_RESULT_EXCHANGE_TYPE
+
+CELERY_RESULT_EXCHANGE_TYPE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The exchange type of the result exchange.  Default is to use a `direct`
+exchange.
+
+.. setting:: CELERY_RESULT_PERSISTENT
+
+CELERY_RESULT_PERSISTENT
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If set to :const:`True`, result messages will be persistent.  This means the
+messages will not be lost after a broker restart.  The default is for the
+results to be transient.
+
+Example configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    CELERY_RESULT_BACKEND = 'amqp'
+    CELERY_TASK_RESULT_EXPIRES = 18000  # 5 hours.
 
 .. _conf-messaging:
 

docs/getting-started/first-steps-with-celery.rst

@@ -223,12 +223,12 @@ built-in result backends to choose from: `SQLAlchemy`_/`Django`_ ORM,
 .. _`SQLAlchemy`: http://www.sqlalchemy.org/
 .. _`Django`: http://djangoproject.com
 
-For this example you will use the `amqp` result backend, which sends states
-as messages.  The backend is specified via the ``backend`` argument to
+For this example you will use the `rpc` result backend, which sends states
+back as transient messages.  The backend is specified via the ``backend`` argument to
 :class:`@Celery`, (or via the :setting:`CELERY_RESULT_BACKEND` setting if
 you choose to use a configuration module)::
 
-    app = Celery('tasks', backend='amqp', broker='amqp://')
+    app = Celery('tasks', backend='rpc://', broker='amqp://')
 
 Or if you want to use Redis as the result backend, but still use RabbitMQ as
 the message broker (a popular combination)::
@@ -333,7 +333,7 @@ current directory or on the Python path, it could look like this:
 .. code-block:: python
 
     BROKER_URL = 'amqp://'
-    CELERY_RESULT_BACKEND = 'amqp://'
+    CELERY_RESULT_BACKEND = 'rpc://'
 
     CELERY_TASK_SERIALIZER = 'json'
     CELERY_RESULT_SERIALIZER = 'json'

docs/userguide/tasks.rst

@@ -693,48 +693,31 @@ Result Backends
 If you want to keep track of tasks or need the return values, then Celery
 must store or send the states somewhere so that they can be retrieved later.
 There are several built-in result backends to choose from: SQLAlchemy/Django ORM,
-Memcached, RabbitMQ (amqp), MongoDB, and Redis -- or you can define your own.
+Memcached, RabbitMQ/QPid (rpc), MongoDB, and Redis -- or you can define your own.
 
 No backend works well for every use case.
 You should read about the strengths and weaknesses of each backend, and choose
 the most appropriate for your needs.
 
-
 .. seealso::
 
     :ref:`conf-result-backend`
 
-RabbitMQ Result Backend
-~~~~~~~~~~~~~~~~~~~~~~~
+RPC Result Backend (RabbitMQ/QPid)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The RabbitMQ result backend (amqp) is special as it does not actually *store*
+The RPC result backend (`rpc://`) is special as it does not actually *store*
 the states, but rather sends them as messages.  This is an important difference as it
-means that a result *can only be retrieved once*; If you have two processes
-waiting for the same result, one of the processes will never receive the
-result!
+means that a result *can only be retrieved once*, and *only by the client
+that initiated the task*. Two different processes can not wait for the same result.
 
 Even with that limitation, it is an excellent choice if you need to receive
 state changes in real-time.  Using messaging means the client does not have to
 poll for new states.
 
-There are several other pitfalls you should be aware of when using the
-RabbitMQ result backend:
-
-* Every new task creates a new queue on the server, with thousands of tasks
-  the broker may be overloaded with queues and this will affect performance in
-  negative ways. If you're using RabbitMQ then each queue will be a separate
-  Erlang process, so if you're planning to keep many results simultaneously you
-  may have to increase the Erlang process limit, and the maximum number of file
-  descriptors your OS allows.
-
-* Old results will be cleaned automatically, based on the
-  :setting:`CELERY_TASK_RESULT_EXPIRES` setting.  By default this is set to
-  expire after 1 day: if you have a very busy cluster you should lower
-  this value.
-
-For a list of options supported by the RabbitMQ result backend, please see
-:ref:`conf-amqp-result-backend`.
-
+The messages are transient (non-persistent) by default, so the results will
+disappear if the broker restarts. You can configure the result backend to send
+persistent messages using the :setting:`CELERY_RESULT_PERSISTENT` setting.
 
 Database Result Backend
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -754,7 +737,6 @@ limitations.
   transaction is committed.  It is recommended that you change to the
   `READ-COMMITTED` isolation level.
 
-
 .. _task-builtin-states:
 
 Built-in States