Grails BackgroundThread Plugin

+----------+
| Overview |
+----------+

This plugin provides your application the ability to throw off background work.  It can be used to provide some 
asynchronous processing in response to key events: the code originally evolved out of parallel web service calls as 
triggered by a Quartz plugin.  Work is processed by a fixed-size thread pool.

Beyond the inherent difficulty of concurrent programming, Grails had a few other difficulties -- most significantly, the 
Hibernate session is bound to the thread, and so threads need to do their own Hibernate session management.

+-------+
| Usage |
+-------+
This plugin provides a service called "backgroundService".  As of now, it provides a single method, "execute", which 
takes two arguments: the name of the work to be executed (an arbitrary label) and a closure which performs the work.

An example usage might be this:

class FooService {
  boolean transactional = false
  def backgroundService

  def serviceMethod() {
    (1..<10).each { cnt ->
      backgroundService.execute("Logging '$cnt' asynchronously", { log.info("${cnt}") })
  }
}

If you have a Runnable kicking around that you wanted to run as some background work, you can access the underlying 
implementation this way:

class BarService {
  boolean transactional = false
  def bgThreadManager

  def serviceMethod() {
    (1..<10).each { 
      bgThreadManager.queueRunnable(new MyRunnable())
  }
}

+----------+
| Warnings |
+----------+
Almost everything you touch in Groovy is not thread-safe, so you need to pass as little information into your closure as 
possible.

Also, you will almost certainly need to crank up the maximum number of connections for your datasource, assuming your 
background work is talking to your database.

+--------------------------------+
| Config Example (Sets Defaults) |
+--------------------------------+
// Drop these lines into ./grails-app/conf/Config.groovy 
// if you want to change defaults.
backgroundThread {
  queueSize = 1000      // Maximum number of tasks to queue up
  threadCount = 5       // Number of threads processing background tasks.
  tasksPerDrain = 100   // See Note
}

* tasksPerDrain -- In concurrent systems, the point of hand-off often becomes a throughput bottleneck.  So when one of 
the background processing threads runs out of work to do, instead of drawing just a single task from the queue, it may 
opt to drain the queue.  This property controls the maximum number of tasks the thread will drain at a time.

+--------------+
| Spring Beans |
+--------------+
* bgExceptionHandler -- A Thread.UncaughtExceptionHandler that is used to handle otherwise uncaught exceptions.
* bgQueue -- The java.util.concurrent.BlockingQueue which stores the tasks to be run.
* bgThreadManager -- The BackgroundThreadManager that manages the background threads and processes.