Readme as rst fragments

queue_job/readme/CONFIGURE.rst

@@ -0,0 +1,43 @@
+* Using environment variables and command line:
+
+  * Adjust environment variables (optional):
+
+    - ``ODOO_QUEUE_JOB_CHANNELS=root:4`` or any other channels configuration. 
+      The default is ``root:1``
+
+    - if ``xmlrpc_port`` is not set: ``ODOO_QUEUE_JOB_PORT=8069``
+
+  * Start Odoo with ``--load=web,queue_job``
+    and ``--workers`` greater than 1. [1]_
+
+
+* Using the Odoo configuration file:
+
+.. code-block:: ini
+
+  [options]
+  (...)
+  workers = 4
+  server_wide_modules = web,queue_job
+
+  (...)
+  [queue_job]
+  channels = root:4
+
+* Confirm the runner is starting correctly by checking the odoo log file:
+
+.. code-block::
+
+  ...INFO...queue_job.jobrunner.runner: starting
+  ...INFO...queue_job.jobrunner.runner: initializing database connections
+  ...INFO...queue_job.jobrunner.runner: queue job runner ready for db <dbname>
+  ...INFO...queue_job.jobrunner.runner: database connections ready
+
+* Create jobs (eg using ``base_import_async``) and observe they
+  start immediately and in parallel.
+
+* Tip: to enable debug logging for the queue job, use
+  ``--log-handler=odoo.addons.queue_job:DEBUG``
+
+.. [1] It works with the threaded Odoo server too, although this way
+       of running Odoo is obviously not for production purposes.

queue_job/readme/DESCRIPTION.rst

@@ -0,0 +1,50 @@
+This addon adds an integrated Job Queue to Odoo.
+
+It allows to postpone method calls executed asynchronously.
+
+Jobs are executed in the background by a ``Jobrunner``, in their own transaction.
+
+Example:
+
+.. code-block:: python
+
+  from odoo import models, fields, api
+  from odoo.addons.queue_job.job import job
+
+  class MyModel(models.Model):
+     _name = 'my.model'
+
+     @api.multi
+     @job
+     def my_method(self, a, k=None):
+         _logger.info('executed with a: %s and k: %s', a, k)
+
+
+  class MyOtherModel(models.Model):
+      _name = 'my.other.model'
+
+      @api.multi
+      def button_do_stuff(self):
+          self.env['my.model'].with_delay().my_method('a', k=2)
+
+
+In the snippet of code above, when we call ``button_do_stuff``, a job capturing
+the method and arguments will be postponed.  It will be executed as soon as the
+Jobrunner has a free bucket, which can be instantaneous if no other job is
+running.
+
+
+Features:
+
+* Views for jobs, jobs are stored in PostgreSQL
+* Jobrunner: execute the jobs, highly efficient thanks to PostgreSQL's NOTIFY
+* Channels: give a capacity for the root channel and its sub-channels and
+  segregate jobs in them. Allow for instance to restrict heavy jobs to be
+  executed one at a time while little ones are executed 4 at a times.
+* Retries: Ability to retry jobs by raising a type of exception
+* Retry Pattern: the 3 first tries, retry after 10 seconds, the 5 next tries,
+  retry after 1 minutes, ...
+* Job properties: priorities, estimated time of arrival (ETA), custom
+  description, number of retries
+* Related Actions: link an action on the job view, such as open the record
+  concerned by the job

queue_job/readme/INSTALL.rst

@@ -0,0 +1 @@
+Be sure to have the ``requests`` library.

queue_job/readme/ROADMAP.rst

@@ -0,0 +1,18 @@
+* After creating a new database or installing ``queue_job`` on an
+  existing database, Odoo must be restarted for the runner to detect it.
+
+* When Odoo shuts down normally, it waits for running jobs to finish.
+  However, when the Odoo server crashes or is otherwise force-stopped,
+  running jobs are interrupted while the runner has no chance to know
+  they have been aborted. In such situations, jobs may remain in
+  ``started`` or ``enqueued`` state after the Odoo server is halted.
+  Since the runner has no way to know if they are actually running or
+  not, and does not know for sure if it is safe to restart the jobs,
+  it does not attempt to restart them automatically. Such stale jobs
+  therefore fill the running queue and prevent other jobs to start.
+  You must therefore requeue them manually, either from the Jobs view,
+  or by running the following SQL statement *before starting Odoo*:
+
+.. code-block:: sql
+
+  update queue_job set state='pending' where state in ('started', 'enqueued')

queue_job/readme/USAGE.rst

@@ -0,0 +1,3 @@
+To use this module, you need to:
+
+#. Go to ``Job Queue`` menu