Implement concept skeleton of the module

Author: mzur

README.md

@@ -1,2 +1,86 @@
-# gpu
-:m: Handle communication with the BIIGLE GPU server
+# BIIGLE GPU Module
+
+Handle communication between BIIGLE and the BIIGLE GPU server.
+
+## Installation
+
+This module needs to be installed both for the BIIGLE instance and the GPU server.
+
+```
+composer config repositories.gpu vcs https://github.com/biigle/gpu
+composer require biigle/gpu
+```
+
+### BIIGLE
+
+The service provider and `Gpu` facade are auto discovered by BIIGLE.
+
+### GPU Server
+
+Add `$app->register(Biigle\Modules\Gpu\GpuServerServiceProvider::class);` to `bootstrap/app.php`.
+
+## Configuration
+
+todo
+
+## Usage
+
+To submit a job to the GPU server, it must extend `Biigle\Modules\Gpu\Jobs\GpuJob`. A job instance can be submitted with `Gpu::push($job)` and will be executed on the GPU server. To return the result data back to the BIIGLE instance, the job must call `$this->submitResponse($response)` at the end of its `handle` method. The response object must extend `Biigle\Jobs\Job` and will be executed on the BIIGLE instance where it can handle storage of the result data.
+
+Be aware that the GPU server has no database access. All required information needs to be stored in the `GpuJob`.
+
+**Example:**
+
+```php
+use Gpu;
+use Biigle\Jobs\Job;
+use Biigle\Modules\Gpu\Jobs\GpuJob;
+
+/*
+ * Instances of this class are submitted to the GPU server with Gpu::push().
+ */
+class MyGpuJob extends GpuJob
+{
+    /*
+     * Instances of this class are created in BIIGLE.
+     */
+    public function __construct($data)
+    {
+        $this->data = $data;
+    }
+
+    /*
+     * But the handle() method is executed on the GPU server.
+     */
+    public function handle()
+    {
+        $result = $this->computeGpuStuff($data);
+        $this->submitResponse(new MyGpuResponse($result));
+    }
+}
+
+/*
+ * Instances of this class are used as argument for GpuJob::submitResponse.
+ */
+class MyGpuResponse extends Job
+{
+    /*
+     * Instances of this class are created on the GPU server.
+     */
+    public function __construct($result)
+    {
+        $this->result = $result;
+    }
+
+    /*
+     * But the handle() method is executed in BIIGLE.
+     */
+    public function handle()
+    {
+        $this->storeResultInDatabase($this->result);
+    }
+}
+
+// In the BIIGLE instance:
+Gpu::push(new MyGpuJob('some data'));
+```

composer.json

@@ -0,0 +1,29 @@
+{
+    "name": "biigle/gpu",
+    "description": "Handle communication between BIIGLE and the BIIGLE GPU server.",
+    "type": "library",
+    "authors": [
+        {
+            "name": "Martin Zurowietz",
+            "email": "martin@cebitec.uni-bielefeld.de"
+        }
+    ],
+    "require": {
+        "guzzlehttp/guzzle": "~6.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "Biigle\\Modules\\Gpu\\": "src"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Biigle\\Modules\\Gpu\\GpuServiceProvider"
+            ],
+            "aliases": {
+                "Gpu": "Biigle\\Modules\\Gpu\\Facades\\Gpu"
+            }
+        }
+    }
+}

src/Adapters/LocalAdapter.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Biigle\Modules\Gpu\Adapters;
+
+use Biigle\Jobs\Job;
+use Biigle\Modules\Gpu\Jobs\GpuJob;
+use Biigle\Modules\Gpu\Contracts\Adapter;
+
+// Push the GpuJob on the "gpu" queue. In the "local" setup the BIIGLE instance and the
+// GPU server share a common Redis cache. This adapter pushes new jobs from BIIGLE to
+// the "gpu" queue and the GPU server picks them up from there. The response is pushed
+// from the GPU server to the regular queue and BIIGLE picks it up from there.
+//
+// In the local setup, only the "worker" service of the GPU server is running.
+
+class LocalAdapter implements Adapter
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function push(GpuJob $job)
+    {
+        //
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function pushResponse(Job $response)
+    {
+        //
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setConfig(array $config)
+    {
+        //
+    }
+}

src/Adapters/OpenStackAdapter.php

@@ -0,0 +1,18 @@
+<?php
+
+// Put this adapter to its own package so not everybody is forced to install all the
+// OpenStack PHP packages!
+
+// This is a wrapper for the Remote adapter. Before the job is pushed, this adapter
+// checks if an OpenStack compute instance is running with the GPU server. It tracks the
+// IPs of the currently active GPU server(s) using the cache. If none is running, it
+// boots one up using a configured image that automatically starts the GPU server. It
+// polls the compute instance until the GPU server responds (with an "idle-since"
+// endpoint?). Then it submits the job using the Remote adapter.
+//
+// This adapter also regularly polls any active GPU servers. If one is idle for a
+// configured time span, the compute instance is destroyed.
+//
+// All this implies that the adapter can manage one or more compute instances. The
+// number can be configured. If more than one instance is available, jobs are submitted
+// round-robin.

src/Adapters/RemoteAdapter.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Biigle\Modules\Gpu\Adapters;
+
+use Biigle\Jobs\Job;
+use Biigle\Modules\Gpu\Jobs\GpuJob;
+use Biigle\Modules\Gpu\Contracts\Adapter;
+
+// Gpu jobs are serialized and transferred via HTTP to the configured URL of the GPU
+// server. The GPU server unserializes the job and processes it. The response is
+// serialized again and transferred back using the responseUrl of the job object.
+// In BIIGLE, the response is unserialized and pushed to the regular queue.
+//
+// This adapter assembles the response URL. It contains a long, unique token for each
+// job. The token is stored in the database until the job response is returned.
+
+class RemoteAdapter implements Adapter
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function push(GpuJob $job)
+    {
+        //
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function pushResponse(Job $response)
+    {
+        //
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setConfig(array $config)
+    {
+        //
+    }
+}

src/Contracts/Adapter.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Biigle\Modules\Gpu\Contracts;
+
+use Biigle\Jobs\Job;
+use Biigle\Modules\Gpu\Jobs\GpuJob;
+
+interface Adapter
+{
+    /**
+     * Submit a job to the GPU server.
+     *
+     * @param GpuJob $job
+     */
+    public function push(GpuJob $job);
+
+    /**
+     * Return a job response back to BIIGLE.
+     *
+     * @param Job $response
+     */
+    public function pushResponse(Job $response);
+
+    /**
+     * Set the configuration of the adapter.
+     *
+     * @param array $config
+     */
+    public function setConfig(array $config);
+}

src/Contracts/GpuJob.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Biigle\Modules\Gpu\Contracts;
+
+use Biigle\Jobs\Job;
+
+interface GpuJob
+{
+    /**
+     * Set the URL of the API endpoint to post the response of this job to.
+     *
+     * @param string $url
+     */
+    public function setResponseUrl($url);
+
+    /**
+     * Get the URL of the API endpoint to post the response of this job to.
+     *
+     * @return string
+     */
+    public function getResponseUrl();
+
+    /**
+     * Submit the response with the results of the processed job.
+     *
+     * @param Job $response
+     */
+    public function submitResponse(Job $response);
+}

src/Facades/Gpu.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Biigle\Modules\Gpu\Facades;
+
+use Illuminate\Support\Facades\Facade;
+
+class Gpu extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string
+     */
+    protected static function getFacadeAccessor()
+    {
+        return 'gpu';
+    }
+}

src/GpuJobHandler.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Biigle\Modules\Gpu;
+
+use Biigle\Jobs\Job;
+use Biigle\Modules\Gpu\Jobs\GpuJob;
+use Biigle\Modules\Gpu\Contracts\Adapter;
+
+class GpuJobHandler
+{
+    /**
+     * The adapter to use for submitting the jobs.
+     *
+     * @var Adapter
+     */
+    protected $adapter;
+
+    /**
+     * Create a new instance.
+     *
+     * @param array $config
+     */
+    public function __construct(array $config)
+    {
+        $this->adapter = new $config['adapter'];
+        $this->adapter->setConfig($config);
+    }
+
+    /**
+     * Submit a job to the GPU server.
+     *
+     * @param GpuJob $job
+     */
+    public function push(GpuJob $job)
+    {
+        $this->adapter->push($job);
+    }
+
+    /**
+     * Return a job response back to BIIGLE.
+     *
+     * @param Job $response
+     */
+    public function pushResponse(Job $response)
+    {
+        $this->adapter->pushResponse($job);
+    }
+}

src/GpuServerServiceProvider.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Biigle\Modules\Gpu;
+
+use Illuminate\Support\ServiceProvider;
+
+class GpuServerServiceProvider extends ServiceProvider
+{
+    /**
+     * Bootstrap the application events.
+     *
+     * @return void
+     */
+    public function boot()
+    {
+        $this->publishes([
+            __DIR__.'/config/gpu.php' => base_path('config/gpu.php'),
+        ], 'config');
+    }
+
+    /**
+     * Register the service provider.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        $this->mergeConfigFrom(__DIR__.'/config/gpu.php', 'gpu');
+    }
+}