From deeaa491ca4e29096b49b048137a8cc8e54544b1 Mon Sep 17 00:00:00 2001
From: Feng <ery.lee@gmail.com>
Date: Sat, 2 Jan 2016 14:46:20 +0800
Subject: [PATCH] 0.2

---
 CHANGES        |  11 ++++++
 README.md      | 101 ++++++++++++++++++++++++++++++++++++++++++++++++-
 src/ecpool.erl |   9 ++++-
 3 files changed, 118 insertions(+), 3 deletions(-)
 create mode 100644 CHANGES

diff --git a/CHANGES b/CHANGES
new file mode 100644
index 000000000..047a612a5
--- /dev/null
+++ b/CHANGES
@@ -0,0 +1,11 @@
+
+0.2-beta (2016/01/02)
+---------------------
+
+Eunit tests and first release.
+
+0.1-beta (2015/12/30)
+---------------------
+
+First commit.
+
diff --git a/README.md b/README.md
index 04ef8a886..c5b89d561 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,99 @@
-# ecpool
-Erlang Connection/Client Pool Library
+# Erlang Connection/Client Pool
+
+ecpool is different with worker-pool libraries in that it is designed to pool connection/clients to server or database.
+
+ecpool tries to avoid the erlang application crash when the server or dabased going down.
+
+
+## Overview
+
+A pool worker to manage and monitor the client to server or database:
+
+```
+PoolWorker -> Client -> DB
+```
+
+Use client:
+
+```
+ecpool:with_client(Pool, fun(Client) -> call(Client) end).
+```
+
+
+## Usage
+
+### Start the pool
+
+```
+ecpool:start_pool(Pool, Mod, Opts).
+```
+
+For example:
+
+```
+PgOpts = [%% Pool Size
+          {pool_size, 10},
+          %% Pool Type: random | hash | round_robin
+          {pool_type, random},
+          %% Auto reconnect
+          {auto_reconnect, 3},
+          %% epgsql opts
+          {host, "localhost"},
+          {port, 5432},
+          {username, "feng"},
+          {password, ""},
+          {database, "mqtt"},
+          {encoding,  utf8}],
+
+ecpool:start_pool(epgsql_pool, epgsql_pool_client, PgOpts)
+
+```
+
+### The Callback Module
+
+Pool Worker Callback:
+
+```
+-callback connect(ConnOpts :: list()) -> {ok, pid()} | {error, any()}.
+```
+
+For example, epgsql_pool_client module:
+
+```
+-module(epgsql_pool_client).
+
+-behavihour(ecpool_worker).
+
+connect(Opts) ->
+    Host = proplists:get_value(host, Opts),
+    Username = proplists:get_value(username, Opts),
+    Password = proplists:get_value(password, Opts),
+    epgsql:connect(Host, Username, Password, conn_opts(Opts)).
+
+squery(Pool, Sql) ->
+    ecpool:with_client(Pool, fun(Client) -> epgsql:squery(Client, Sql) end).
+```
+
+## Design
+
+The ecpool supervisor tree:
+
+```
+pool_sup[one_for_all supervisor]
+    pool[gen-server]
+    worker_sup[one_for_one supervisor]
+        worker1 -> connection1
+        worker2 -> connection1
+        ....
+```
+
+## Author
+
+Feng Lee <feng@emqtt.io>
+
+
+## License
+
+The MIT License (MIT)
+
+
diff --git a/src/ecpool.erl b/src/ecpool.erl
index 97668c06f..8934bf3c4 100644
--- a/src/ecpool.erl
+++ b/src/ecpool.erl
@@ -29,8 +29,15 @@
 -export([start_pool/3, start_sup_pool/3, stop_sup_pool/1,
          with_client/2, with_client/3, name/1, workers/1]).
 
+-type pool_type() :: random | hash | round_robin.
+
+-type option() :: {pool_size, pos_integer()}
+                | {pool_type, pool_type()}
+                | {auto_reconnect, false | pos_integer()}
+                | tuple().
+
 %% @doc Start the pool
--spec start_pool(atom(), atom(), list()) -> {ok, pid()} | {error, any()}.
+-spec start_pool(atom(), atom(), [option()]) -> {ok, pid()} | {error, any()}.
 start_pool(Pool, Mod, Opts) when is_atom(Pool) ->
     ecpool_pool_sup:start_link(Pool, Mod, Opts).