# Expool
[![Build Status](https://travis-ci.org/zackehh/expool.svg?branch=master)](https://travis-ci.org/zackehh/expool) [![Coverage Status](https://coveralls.io/repos/zackehh/expool/badge.svg?branch=master&service=github)](https://coveralls.io/github/zackehh/expool?branch=master)
A simple Process pooling library to avoid having to repeatedly write the boilerplate into your projects. Supports a couple of cool options, but nothing too crazy (yet).
## Installation
The package can be installed via Hex:
1. Add expool to your list of dependencies in `mix.exs`:
def deps do
[{:expool, "~> 0.1.0"}]
end
2. Ensure expool is started before your application:
def application do
[applications: [:expool]]
end
## Usage
The general idea is that you create a pool and then submit tasks to it, pretty straightforward stuff:
```elixir
pool = Expool.create_pool(3) # 3 workers
# `pid` is the Process submitted to, in case you wish
# to send any messages.
{ :ok, pid } = Expool.submit(pool, fn ->
:timer.sleep(5000)
IO.puts("Success!")
end)
```
Once you're done with it, you can terminate your pool:
```elixir
pool = Expool.create_pool(3)
pool = Expool.terminate(pool)
```
Terminating means that all Processes referenced in the pool are killed using `:shutdown`. This means that sending messages to them will not work (because they're dead). To make this a little nicer, the pool returned by `terminate/1` has an internal flag marking the pool as inactive. This means that you'll receive an error tuple if you try to submit a task to it, allowing you to `case` on the submission.
```elixir
pool = Expool.create_pool(3)
pool = Expool.terminate(pool)
{ :ok, pid } = Expool.submit(pool, fn ->
:timer.sleep(5000)
IO.puts("Success!")
end)
** (MatchError) no match of right hand side value: {:error, "Task submitted to inactive pool!"}
```
## Options
### args
It's sometimes nice to have your Agent supplied with arguments, so that you don't have to care about scoping. Due to this, Expool allows you to specify a list of arguments to be provided to your task scope. You do this by providing an `args` option to `create_pool`, and return a list of the arguments you want to bind. If you wish to pass a single list argument, remember to wrap it up, e.g. `[[head]]` (otherwise you would get `head` as an arg).
It should be noted that your `args` function is executed N times for the number of workers. This sounds stupid (and maybe it is), but the reasoning is that you might wish to open N different database connections (my Elixir isn't good here; does the memory copying between Processes mean that you would share connection otherwise?). If you want to avoid this, just make your connection outside, then make the `args` function return it.
```elixir
pool = Expool.create_pool(3, args: fn ->
[my_database_client]
end)
{ :ok, pid } = Expool.submit(pool, fn(client) ->
:timer.sleep(5000)
IO.puts("Success with a client!")
end)
```
### register
One of the harder things to get used to with Elixir is the scoping; for this reason, you can `register` your pool in a namespace (which literally just uses an `Agent` behind the scenes). This allows you to retrieve your pool from anywhere in your application effortlessly.
```elixir
# setup the pool
pool = Expool.create_pool(3, register: :mysql_pool)
# somewhere else in your application
pool = Expool.get_pool(:mysql_pool)
# you can submit to a registered name - this is one of the nicer
# features, because you can blindly use Expool from anywhere
{ :ok, pid } = Expool.submit(:mysql_pool, fn ->
:timer.sleep(5000)
IO.puts("Success with a client!")
end)
```
### strategy
By default, Expool uses round-robin strategy methods to pass tasks to the pool. This will just rotate the index used for starting a task, before looping around all potential PIDs.
```elixir
pool = Expool.create_pool(3, register: :mysql_pool, strategy: :round_robin)
# this will shift the index
{ :ok, pid } = Expool.submit(pool, fn ->
:timer.sleep(5000)
IO.puts("Success with a client!")
end)
# the next time you submit using `pool`, the
# next process will receive the task
{ :ok, pid } = Expool.submit(pool, fn ->
:timer.sleep(5000)
IO.puts("Success with a client!")
end)
# using a name means that it's always synced
{ :ok, pid } = Expool.submit(:mysql_pool, fn ->
:timer.sleep(5000)
IO.puts("Success with a client!")
end)
```
The only other currently available selection type is `:random`, but I may add load-based options in future.
## Issues
If you find anything broken in here, please file an issue or a pull request. I wrote this whilst bored on a layover, so it's probably not the best.