Gearbox Architecture
--------------------

There are four major components to a service built with gearbox:

   * gearman
   * mod_gearbox
   * gearbox workers and delay daemon
   * your workers

[gearman](http://gearman.org/) is used by gearbox as a job server.  All workers
are gearman clients: they connect to gearman to get jobs to work on and to
submit child jobs.  Although gearman is currently the only implementation for
jobs, gearbox is abstracts all gearman interaction into a single class
(gearbox/job/GearmanJobImpl.cc), so it should be straightforward to add other
backends.  In fact, there's been a fair amount of discussion around adding an
AMQP implemenetation.

mod_gearbox is an apache module that ships with gearbox.  It will take HTTP
requests and marshal them into jobs.  By default, GETs are syncronous and hold
the HTTP connection open until the job completes and then return the job
response back to the user.  PUTs, POSTs, and DELETEs are done asyncronously, so
mod_gearbox returns a status object back to the user which the user can poll
to track the status of an operation.  mod_gearbox is not strictly required,
but a primary usecase of gearbox is building REST web services.

Gearbox workers are primarily used to generate status objects that track the
state of a job.  These workers are also used to help implement features like
delayed jobs, cancellations and agents.  The gearbox delay daemon manages jobs
which are scheduled to run in the future.

See http://getgearbox.org for more information.


License
-------

All file copyrights licensed under the New BSD License with the exception of
the Perl files listed below which are licensed under the Perl Artistic License.
See the accompanying LICENSE and LICENSE.Artistic files for terms.

Files licensed under Perl Artistic License:

  ./tools/svcbuilder/lib/Gearbox/Service/Builder.pm
  ./tools/svcbuilder/lib/Gearbox/Service/Entry.pm
  ./tools/svcbuilder/lib/Gearbox/Utils.pm
  ./tools/client/gearbox.pl
  ./perl/Gearbox_Rest_Client/Gearbox/Rest/Client.pm
  ./gearbox/t/core/httpd.pl
  ./gearbox/t/swig/perl/setup.pm
  ./gearbox/swig/perl/lib/Gearbox/ConfigFile.pm
  ./gearbox/swig/perl/lib/Gearbox/JobManager.pm
  ./gearbox/swig/perl/lib/Gearbox/Worker.pm
  ./gearbox/swig/perl/lib/Gearbox/StopWatch.pm
  ./gearbox/swig/perl/lib/Gearbox/StatusManager.pm
  ./gearbox/swig/perl/lib/Gearbox/Logger.pm
  ./common/build/gen_handlers_dir.pl
  ./common/build/svn_ignore.pl
  ./common/build/gen_handler_table.pl
  ./workers/test-perl/workerTestPerl.pl
  ./workers/test-cancel/perl/workerTestCancel.pl
  ./workers/test-chained/perl/workerTestChained.pl
  ./workers/test-sync/perl/workerTestSync.pl
  ./workers/test-delay/perl/workerTestDelay.pl
  ./workers/test-agents/perl/workerTestAgents.pl
  ./workers/test-basic/perl/workerTestBasic.pl

3rd Party Source:

This product includes PHP software, freely available from  <http://www.php.net/software/>

  ./gearbox/swig/php/php_Json_helper.h
  ./gearbox/swig/php/var_dump.h

These above files contain modified code from the PHP project licensed as follows:

  +----------------------------------------------------------------------+
  | PHP Version 5                                                        |
  +----------------------------------------------------------------------+
  | Copyright (c) 1997-2010 The PHP Group                                |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | http://www.php.net/license/3_01.txt                                  |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+

Dependencies
------------

Required Dependencies:

log4cxx - http://logging.apache.org/log4cxx/
boost - http://boost.org
curl - http://curl.haxx.se/
gearman C - https://launchpad.net/gearmand
openssl - http://openssl.org
soci - http://soci.sourceforge.net/
yajl - http://lloyd.github.com/yajl

Optional Dependencies:

libzookeeper - c bindings for zookeeper
             http://zookeeper.apache.org
libtap++ - TAP testing interface in C++
           http://code.google.com/p/libperl/wiki/Libtap
swig-2.x - http://swig.org
php5 - Zend for PHP Swig bindings - http://php.net
apache2 - http://httpd.apache.org