Merge branch 'dev'

toplan · May 15, 2017 · 114204e · 114204e
2 parents f260019 + 758d853
commit 114204e
Show file tree

Hide file tree

Showing 8 changed files with 459 additions and 444 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.idea/
diff --git a/README.md b/README.md
@@ -1,53 +1,56 @@
 # Intro
-lightweight and powerful task load balancing for php
 
-> like the `nginx` load balancing :)
+[![Latest Stable Version](https://img.shields.io/packagist/v/toplan/task-balancer.svg)](https://packagist.org/packages/toplan/task-balancer)
+[![Total Downloads](https://img.shields.io/packagist/dt/toplan/task-balancer.svg)](https://packagist.org/packages/toplan/task-balancer)
+
+Lightweight and powerful task load balancing.
+
+> like the `nginx` load balancing :smile:
 
 # Features
 
 - Support multiple drives for every task.
-- Automatically choose a driver to execute task by drivers` weight value.
+- Automatically choose a driver to execute task by drivers' weight value.
 - Support multiple backup drivers.
 - Task lifecycle and hooks system.
 
 # Install
 
 ```php
-    composer require 'toplan/task-balancer:~0.4.2'
+composer require toplan/task-balancer:~0.5
 ```
 
 # Usage
 
 ```php
 //define a task
 Balancer::task('task1', function($task){
-
     //define a driver for current task like this:
-    $task->driver('driver_1 100 backup', function($driver, $data){
-                    //do something here
-                    ...
-                    //set whether run success/failure at last
-                    if ($success) {
-                        $driver->success();
-                    } else {
-                        $driver->failure();
-                    }
-                    //return some data you need
-                    return 'some data here';
-                });
+    $task->driver('driver_1 100 backup', function ($driver, $data) {
+        //do something here
+        ...
+        //set whether run success/failure at last
+        if ($success) {
+            $driver->success();
+        } else {
+            $driver->failure();
+        }
+        //return some data you need
+        return 'some data you need';
+    });
 
     //or like this:
-    $task->driver('driver_2', 90, function($driver, $data){
-                //...same as above..
-         })->data(['this is data 2']);
+    $task->driver('driver_2', 90, function ($driver, $data) {
+        //...same as above..
+    })->data(['this is data 2']);
 
     //or like this:
     $task->driver('driver_3')
-         ->weight(0)->backUp()
-         ->data(['this is data 3'])
-         ->work(function($driver, $data){
-                    //...same as above..
-                });
+    ->weight(0)->backUp()
+    ->data(['this is data 3'])
+    ->work(function ($driver, $data) {
+        //...same as above..
+    });
 });
 
 //run the task
@@ -70,7 +73,7 @@ The `$result` structure:
                 'started_at' => timestamp,
                 'finished_at' => timestamp
             ],
-            'result' => 'some data here'
+            'result' => 'some data you need'
         ],
         ...
     ]
@@ -79,113 +82,128 @@ The `$result` structure:
 
 # API
 
-## 1. Create & Run
+## Balancer
 
-### Balancer::task($name [, $data], $work);
+### Balancer::task($name[, $data][, Closure $ready]);
 
-create a task instance, return task instance.
+Create a task instance, and return it.
+The closure `$ready` immediately called with argument `$task`.
 
 ```php
 Balancer::task('taskName', $data, function($task){
-    //task`s ready work, like create drivers
+    //task's ready work, such as create drivers.
 });
 ```
 
-> `$data` will store in task instance.
+> `$data` will store in the task instance.
+
+### Balancer::run($name[, array $options])
 
-### Balancer::run($taskName [, array $opts])
+Run the task by name, and return the result data.
 
-run the task, and return a result array.
+The keys of `$options`:
+- `data`
+- `driver`
 
-The $opts value:
-* $opts['data']
-* $opts['driver']
+## Task
 
-### $task->data($data)
+### name($name)
 
-set the data value of task instance, will override origin data.
+set the name of task.
 
-### $task->driver($optionString [, $weight] [, 'backup'], $work);
+### data($data)
 
-create a driver instance for `$task`, return driver instance.
+Set the data of task.
 
-> `$weight` must be a integer, default value is '1'
+### driver($config[, $weight][, 'backup'], Closure $work)
+
+Create a driver for the task. The closure `$work` will been called with arguments `$driver` and `$data`.
+
+> Expected `$weight` to be a integer, default `1`.
 
 ```php
 $task->driver('driverName 80 backup', function($driver, $data){
-    //driver`s work
-    //$driver is driver instance
+    //driver's job content.
 });
 ```
 
-### $driver->weight($weight)
+### hasDriver($name)
+
+Whether has the specified driver.
+
+### getDriver($name)
+
+Get driver by name.
 
-set driver`s weight, return current driver,
-supported chain operation.
+### removeDriver($name)
 
-> `$weight` must be a integer
+Remove driver from drivers' pool by name.
 
-### $driver->backup($is)
+## Driver
 
-set driver is backup, return current driver,
-supported chain operation.
+### weight($weight)
 
-> `$is` must be true of false
+Set the weight value of driver.
 
-### $driver->data($data);
+### backup($is)
 
-set the data value of driver instance,
-support chain operation.
+Set whether backup driver.
+
+> Expected `$is` to be boolean, default `true`.
+
+### data($data)
+
+Set the data of driver.
 
 > `$data` will store in driver instance.
 
-### $driver->work(function($driver, $data){});
+### work(Closure $work);
 
-set driver work, give two arguments: `$driver` and `$data`,
-support chain operation.
+Set the job content of driver.
 
-> `$data` is a value try to get from driver instance,
-if null will continue try to get from task instance.
->
 > `$data` equals to `$driver->getData()`
 
-### $driver->failure()
+### reset($config[, $weight][, 'backup'], Closure $work)
 
-set current driver run failed,
-support chain operation.
+Reset driver's weight value, job content and reset whether backup.
 
-### $driver->success()
+### destroy()
 
-set current driver run successful.
-support chain operation.
+Remove the driver from task which belongs to.
 
-### $driver->getDriverData()
+### failure()
 
-get data value of driver instance.
+Set the driver running failure.
 
-### $driver->getTaskData()
+### success()
 
-get data value of task instance.
+Set the driver run successfully.
 
+### getDriverData()
 
-## 2. Task Lifecycle
+Get the data which store in driver instance.
 
-> support multiple handlers for every hook!
+### getTaskData()
 
-###Hooks Table
+Get the data which store in task instance.
 
-| Hook name | handler arguments | influence of the last handler`s return value |
-| --------- | :----------------: | :-----: |
-| beforeCreateDriver | $task, $preReturn, $index, $handlers | no effect |
-| afterCreateDriver | $task, $preReturn, $index, $handlers | no effect |
-| beforeRun | $task, $preReturn, $index, $handlers | if `false` will stop run task and return `false` |
-| beforeDriverRun | $task, $driver, $preReturn, $index, $handlers | if `false` will stop to use current driver and try to use next backup driver |
-| afterDriverRun | $task, $driverResult, $preReturn, $index, $handlers | no effect |
-| afterRun | $task, $taskResult, $preReturn, $index, $handlers | if not boolean will override result value |
 
-###Use Hooks
+## Lifecycle & Hooks
+
+> Support multiple handlers for every hooks!
 
-> `$override` default value is `false`, if `true` will override hook handlers.
+### Hooks
+
+| Hook name | handler arguments | influence of the last handler's return value |
+| --------- | :----------------: | :-----: |
+| beforeCreateDriver | $task, $props, $index, &$handlers, $prevReturn | if an array will been merged into original props |
+| afterCreateDriver | $task, $driver, $index, &$handlers, $prevReturn | - |
+| beforeRun | $task, $index, &$handlers, $prevReturn | if `false` will stop run task and return `false` |
+| beforeDriverRun | $task, $driver, $index, &$handlers, $prevReturn | if `false` will stop to use current driver and try to use next backup driver |
+| afterDriverRun | $task, $driverResult, $index, &$handlers, $prevReturn | - |
+| afterRun | $task, $taskResult, $index, &$handlers, $prevReturn | if not boolean will override result value |
+
+### Usage
 
 * $task->hook($hookName, $handler, $override)
 
@@ -201,40 +219,32 @@ get data value of task instance.
 
 * $task->afterRun($handler, $override)
 
+> `$override` default `false`.
 
 ```php
 //example
-$task->beforeRun(function($task, $preReturn, $index, $handlers){
-    //what is $preReturn?
-    $preReturn == null; //true
+$task->beforeRun(function($task, $index, $handlers, $prevReturn){
+    //what is $prevReturn?
+    echo $prevReturn == null; //true
     //what is $index?
-    $index == 0; //true
+    echo $index == 0; //true
     //what is $handlers?
     echo count($handlers); //2
     //do something..
     return 'beforeRun_1';
 }, false);
 
-$task->beforeRun(function($task, $preReturn, $index, $handlers){
-    //what is $preReturn?
-    $preReturn == 'beforeRun_1'; //true
+$task->beforeRun(function($task, $index, $handlers, $prevReturn){
+    //what is $prevReturn?
+    echo $prevReturn == 'beforeRun_1'; //true
     //what is $index?
-    $index == 1; //true
+    echo $index == 1; //true
     //what is $handlers?
     echo count($handlers); //2
     //do other something..
 }, false);
 ```
 
-# Todo
-
-- [x] remember every task`s start time and end time.
-- [x] remember every driver`s start time and end time.
-- [x] smart parse arguments of method `driver()`.
-- [x] task lifecycle and hooks
-- [ ] hot remove/add a driver.
-- [ ] pause/resume task
-
 # Dependents
 
 - [phpsms](https://github.com/toplan/phpsms)

diff --git a/composer.json b/composer.json
@@ -1,9 +1,8 @@
 {
   "name": "toplan/task-balancer",
-  "description": "lightweight and powerful task load balancing for php (like the nginx load balancing)",
+  "description": "lightweight and powerful task load balancing.",
   "license": "MIT",
-  "version": "0.4.2",
-  "keywords": ["task", "balance", "load balancing", "balancer"],
+  "keywords": ["task", "balance", "load balancing"],
   "authors": [
     {
       "name": "toplan",
@@ -17,6 +16,5 @@
     "psr-4": {
       "Toplan\\TaskBalance\\": "src/TaskBalancer/"
     }
-  },
-  "minimum-stability" : "dev"
-}
+  }
+}