Unit tests and I/O bindings (#8)

* Added composer config, added IO/error tests using phpunit

* Added ApiGen doc comments

* Added test to ensure last_error is not set from loading up the CRT

.gitignore

@@ -193,3 +193,4 @@ config.nice
 *.la
 Makefile*
 !Makefile.am
+/vendor/

composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "aws/awscrt",
+    "description": "AWS Common Runtime for PHP",
+    "type": "library",
+    "require": {
+
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^5"
+    },
+    "conflict": {
+        "phpunit/php-timer": ">=2"
+    },
+    "autoload-dev": {
+        "classmap": [
+            "lib/"
+        ]
+    },
+    "autoload": {
+        "files": ["lib/preload.php"]
+    },
+    "scripts": {
+        "test": "phpunit --bootstrap lib/lib.php"
+    },
+    "license": "Apache-2.0",
+    "authors": [
+        {
+            "name": "AWS Common Runtime Team",
+            "email": "[email protected]"
+        }
+    ]
+}

lib/crt.php

@@ -1,35 +1,105 @@
 <?php
-require_once('preload.php');
 
+/**
+ * Wrapper for the FFI interface to the CRT. There only ever needs to be one of these.
+ * Creating an instance of any NativeResource will activate the CRT binding. User code
+ * should only need to create one of these if they are only accessing CRT:: functions.
+ */
 final class CRT {
     private static $ffi = null;
+    private static $refcount = 0;
+
     function __construct() {
         if (is_null(self::$ffi)) {
             try {
                 self::$ffi = FFI::cdef(file_get_contents(__DIR__ . "/api.h"), __DIR__ . "/libaws-crt-ffi.so");
+                self::init();
             } catch (Exception $e) {
-                echo 'Exception: ', $e->getMessage(), "\n";
+                echo 'Exception while initializing CRT via FFI: ', $e->getMessage(), "\n";
             }
         }
+        ++self::$refcount;
+    }
+
+    function __destruct() {
+        if (--self::$refcount == 0) {
+            self::clean_up();
+            self::$ffi = null;
+        }
     }
 
-    function init() {
+    private static function init() {
         return self::$ffi->aws_crt_init();
     }
 
-    function clean_up() {
+    private static function clean_up() {
         return self::$ffi->aws_crt_clean_up();
     }
 
-    function last_error() {
+    /**
+     * @return integer last error code reported within the CRT
+     */
+    public static function last_error() {
         return self::$ffi->aws_crt_last_error();
     }
 
-    function error_str($error) {
+    /**
+     * @param integer $error Error code from the CRT, usually delivered via callback or {@see last_error}
+     * @return string Human-readable description of the provided error code
+     */
+    public static function error_str($error) {
         return self::$ffi->aws_crt_error_str((int) $error);
     }
 
-    function error_name($error) {
+    /**
+     * @param integer $error Error code from the CRT, usually delivered via callback or {@see last_error}
+     * @return string Name/enum identifier for the provided error code
+     */
+    public static function error_name($error) {
         return self::$ffi->aws_crt_error_name((int) $error);
     }
+
+    function event_loop_group_new($options) {
+        return self::$ffi->aws_crt_event_loop_group_new($options->num_threads);
+    }
+
+    function event_loop_group_release($elg) {
+        return self::$ffi->aws_crt_event_loop_group_release($elg);
+    }
+}
+
+/**
+ * Base class for all native resources, tracks all outstanding resources
+ * and provides basic leak checking
+ */
+abstract class NativeResource {
+    protected static $crt = null;
+    protected static $resources = [];
+    protected $native = null;
+
+    function __construct() {
+        if (is_null(self::$crt)) {
+            try {
+                self::$crt = new CRT();
+            } catch (Exception $e) {
+                echo 'Exception while loading CRT: ', $e->getMessage(), "\n";
+            }
+        }
+
+        self::$resources[spl_object_hash($this)] = 1;
+    }
+
+    protected function acquire($handle) {
+        $this->native = $handle;
+    }
+
+    protected function release() {
+        $this->native = null;
+    }
+
+    function __destruct() {
+        // Should have been destroyed and released by derived resource
+        assert($this->native == null);
+        unset(self::$resources[spl_object_hash($this)]);
+    }
 }

lib/io.php

@@ -0,0 +1,27 @@
+<?php
+
+require_once('crt.php');
+
+final class EventLoopGroupOptions {
+    /**
+     * @var int $num_threads - Number of worker threads in the EventLoopGroup. Defaults to 0/1 per logical core.
+     */
+    public $num_threads = 0;
+}
+
+/**
+ * Represents 1 or more event loops (1 per thread) for doing I/O and background tasks.
+ * Typically, every application has one EventLoopGroup.
+ */
+final class EventLoopGroup extends NativeResource {
+    function __construct($options) {
+        parent::__construct();
+        $this->acquire(self::$crt->event_loop_group_new($options->num_threads));
+    }
+
+    function __destruct() {
+        self::$crt->event_loop_group_release($this->native);
+        $this->release();
+        parent::__destruct();
+    }
+}

lib/lib.php

@@ -0,0 +1,7 @@
+<?php
+
+// Entry point to the CRT library. This file should be preloaded.
+
+// Import all of the library modules
+require_once('crt.php');
+require_once('io.php');

lib/preload.php

@@ -3,5 +3,5 @@
 // ffi.enable=preload
 // opcache.preload=preload.php
 if (function_exists("opcache_compile_file")) {
-    opcache_compile_file(__DIR__ . "/crt.php");
+    opcache_compile_file(__DIR__ . "/lib.php");
 }

lib/tests/ErrorTest.php

@@ -0,0 +1,26 @@
+<?php
+
+require_once('tests.inc');
+
+final class ErrorTest extends PHPUnit_Framework_TestCase {
+    private static $crt = null;
+    public static function setUpBeforeClass() {
+        self::$crt = new CRT();
+    }
+
+    public static function tearDownAfterClass() {
+        self::$crt = null;
+    }
+
+    public function testNoInitialError() {
+        $this->assertEquals(0, CRT::last_error());
+    }
+
+    public function testCanResolveErrorName() {
+        $this->assertEquals("AWS_ERROR_SUCCESS", CRT::error_name(0));
+    }
+
+    public function testCanResolveErrorStr() {
+        $this->assertEquals("Success.", CRT::error_str(0));
+    }
+}

lib/tests/EventLoopGroupTest.php

@@ -0,0 +1,18 @@
+<?php
+
+require_once('tests.inc');
+
+final class EventLoopGroupTest extends PHPUnit_Framework_TestCase {
+
+    public function testLifetime() {
+        $elg = new EventLoopGroup(new EventLoopGroupOptions());
+        $elg = null;
+    }
+
+    public function testConstructionWithOptions() {
+        $options = new EventLoopGroupOptions();
+        $options->num_threads = 1;
+        $elg = new EventLoopGroup($options);
+        $elg = null;
+    }
+}

lib/tests/tests.inc

@@ -0,0 +1,9 @@
+<?php
+
+// Ensure any version of PHPUnit works, since phpunit5 is the last one that
+// works with PHP5.6
+if (!class_exists('PHPUnit_Framework_TestCase') &&
+  class_exists('\\PHPUnit\\Framework\\TestCase')) {
+    abstract class PHPUnit_Framework_TestCase extends \PHPUnit\Framework\TestCase {
+    }
+}