eFaw

eFaw 是一个轻量级的 Erlang worker 编排库，围绕三种运行模式展开：

1. worker 模式：固定命名 worker，直接分发任务 适用于任务处理时间比较短的任务
2. factory 模式：任务队列加弹性 worker，适用于可能单个任务处理时间不确定的场景 别的任务不会因为一个任务耗时太长而导致别的任务跟着等待
3. pool 模式：借出并归还 worker 进程，适合一次操作中独占某个 worker 的场景 比如说数据驱动 主要是为了支持一下原生的一些数据库驱动库的写法

项目依赖 eGbh 和 eLfq，其中 eLfq 作为 factory 与 pool 模式底层的无锁队列实现。

编译

rebar3 compile

启动与停止

eFaw:start().
eFaw:stop().

Worker 模块约定

src/Faw/fwWTP.erl 是默认的 worker 实现。如果你通过 wMod 指定自定义 worker 模块，需要兼容以下回调形式：

1. start_link/3：用于 factory 和 pool worker
2. start_link/4：用于固定命名 worker
3. work/1：执行具体任务

配置项

通用配置定义在 include/eFaw.hrl：

1. wMod：worker 模块，默认值是 fwWTP
2. wFCnt：固定 worker 数量，默认值是 30
3. wTCnt：临时 worker 数量上限，默认值是 20
4. wKeepTime：空闲保留时间，单位毫秒，默认值是 3600000
5. fTLfl：factory 任务负载阈值，默认值是 10000
6. fTMax：允许接收的最大任务队列长度，默认值是 infinity
7. wArgs：worker 初始化参数

Worker 模式

Worker 模式会创建一组固定命名的 worker，并直接把任务分发给这些 worker。

eFaw:openW(my_worker_group, [
    {wMod, fwWTP},
    {wFCnt, 8},
    {wArgs, undefined}
]).

eFaw:doWork(my_worker_group, task1).
eFaw:doSyncWork(my_worker_group, task2).
eFaw:closeW(my_worker_group).

主要接口：

1. start/0
2. stop/0
3. openW/2
4. closeW/1
5. getWork/1
6. getWork/2
7. doWork/2
8. doWork/3
9. doSyncWork/2
10. doSyncWork/3
11. doSyncWork/4

Factory 模式

Factory 模式会维护一个任务队列。空闲 worker 会优先直接消费任务，当负载超过设定阈值时，manager 可以按配置补充临时 worker。

eFaw:openF(my_factory, [
    {wMod, fwWTP},
    {wFCnt, 4},
    {wTCnt, 8},
    {fTLfl, 100},
    {fTMax, 10000}
]).

eFaw:inWork(my_factory, task1).
eFaw:inWorks(my_factory, [task1, task2, task3]).
eFaw:inSyncWork(my_factory, task2).
eFaw:sizeF(my_factory).
eFaw:closeF(my_factory).

主要接口：

1. openF/2
2. closeF/1
3. sizeF/1
4. hireW/3
5. inWork/2
6. inWorks/2
7. inSyncWork/2
8. inSyncWork/3

Pool 模式

Pool 模式适合这样的场景：调用方需要借出一个 worker 进程，围绕这个 worker 执行一段逻辑，完成后再把它归还。

eFaw:openPool(my_pool, [
    {wMod, fwWTP},
    {wFCnt, 16},
    {wKeepTime, 60000},
    {wArgs, undefined}
]).

手动借出和归还：

Pid = eFaw:checkout(my_pool),
Ret = my_worker_api:do_something(Pid),
eFaw:checkIn(my_pool, Pid).

或者使用 transaction/2 保证自动归还：

eFaw:transaction(my_pool, {fun(Pid) ->
    my_worker_api:do_something(Pid)
end, []}).

eFaw:transaction(my_pool, {my_worker_api, do_something, [Arg1, Arg2]}).

主要接口：

1. openPool/2
2. closePool/1
3. hireP/2
4. checkout/1
5. checkIn/2
6. alivePWorker/1
7. transaction/2

Pool 使用说明

1. checkOut/1 成功时直接返回 worker 的 pid；如果进程池不存在或已满，则返回错误元组。
2. checkIn/2 正常情况下应当使用进程池名称和 worker pid 进行归还。
3. transaction/2 是更安全的 pool 接口，因为即使回调抛错，它也能保证 worker 被归还。
4. wKeepTime 用来控制 pool worker 最长允许空闲多久，超过后会被 pool manager 清理。

示例 Worker

最小可运行的 worker 示例可以参考 src/Faw/fwWTP.erl。