README.md

# ElixirTalk

## Overview
`ElixirTalk` is an Elixir client for [beanstalkd](http://kr.github.com/beanstalkd/).
It supported all commands defined in [Beanstalkd Protocol](https://raw.github.com/kr/beanstalkd/master/doc/protocol.txt)

## Installation & Setup

First, add ElixirTalk to your `mix.exs` dependencies:

```elixir
def deps do
  [{:elixir_talk, "~> 1.0.2"}]
end
```

and run `$ mix deps.get`.

## Getting Started
You'll need **beanstalkd** listening at the host: `10.1.1.5`, and port: `14711`, simply start it with:
`$ beanstalkd -l 10.1.1.5 -p 14711`

Start the interactive shell and run the `ElixirTalk.connect` method to run it:

    iex -S mix
    iex(1)> {:ok, pid} = ElixirTalk.connect('10.1.1.5', 14711)
If you leave out the two arguments, `'127.0.0.1'` and `11300` are the default value, also there is a `timeout` parameter
which determines how long, **in millliseconds**, the socket will wait for **beanstalkd** to respond to its' initial
connection, default to `:infinity`.

## Basic Operation
After connection to the beanstalkd successfully, we can enqueue our jobs:

    iex(2)> ElixirTalk.put(pid, "hello world")
    {:inserted, 1}

Or we can get jobs:

    iex(3)> ElixirTalk.reserve(pid)
    {:reserved, 1, {11, "hello world"}}

Once we are finishing a job, we have to delete it, otherwise jobs are re-queued by **beanstalkd**
after a `:ttr` "time to run" (60 seconds, per default) is surpassed. A job is marked as finished, by calling delete:

    iex(4)> ElixirTalk.delete(pid, 1)
    :deleted

`reserve` blocks until a job is ready, possibly forever. We can invoke reserve with a timeout **in seconds**,
to indicate how long we want to wait to receive a job. If such a reserve times out, it will return `:timed_out`:

    iex(5)> ElixirTalk.reserve(pid, 5)
    :timed_out

If you use a timeout of 0, reserve will immediately return either a job or `:timed_out`.

## Tube Management

A single **beanstalkd** server can provide many different queues, called "tubes" in **beanstalkd**.
To see all available tubes:

    iex(6)> ElixirTalk.list_tubes(pid)
    ["default"]

A **beanstalkd** client can choose one tube into which its job are putted. This is the tube "used" by the client.
To see what tube you are currently using:

    iex(7)> ElixirTalk.list_tube_used(pid)
    {:using, "default"}

Unless told otherwise, a client uses the `"default"` tube. If you want to use a different tube:

    iex(8)> ElixirTalk.use(pid, "notDefault")
    {:using, "notDefault"}
    iex(8)> ElixirTalk.list_tube_used(pid)
    {:using, "notDefault"}

If you decide to use a tube which does not yet exist, the tube is automatically created by **beanstalkd**, so you can see
we initially used the `"default"` tube. Of course, you can always switch back to the default tube.
Tubes that don't have any client using or watching, be vanished automatically:

    iex(9)> ElixirTalk.list_tubes(pid)
    ["default", "notDefault"]
    iex(10)> ElixirTalk.use(pid, "default")
    {:using, "default"}
    iex(11)> ElixirTalk.list_tubes(pid)
    ["default"]

Further more, a beanstalkd client can choose many tubes to `reserve` jobs from. These tubes are `watched` by the client.
To see what tubes you are currently watching:

    iex(12)> ElixirTalk.list_tubes_watched(pid)
    ["default"]

To watch an additional tube:

    iex(13)> ElixirTalk.watch(pid, "notDefault")
    {:watching, 2}
    iex(14)> ElixirTalk.list_tubes_watched(pid)
    ["default", "notDefault"]

The same to `use`, tubes that do not yet exist are created automatically once you start watching them.

To stop `watch` a tube:

    iex(15)> ElixirTalk.ignore(pid, "default")
    {:watching, 1}
    iex(16)> ElixirTalk.list_tubes_watched(pid)
    ["notDefault"]

You can't watch zero tubes. So if you try to ignore the last tube you are watching, this is silently return `:not_ignored`:

    iex(17)> ElixirTalk.ignore(pid, "notDefault")
    :not_ignored
    iex(18)> ElixirTalk.list_tubes_watched(pid)
    ["notDefault"]

Note that `use` and `watch` these concerns are fully orthogonal: for example, when you use a tube, it is not
automatically watched. Neither does watching a tube affect the tube you are using. You may `use` a tube in one process
to put your jobs, while in another process you `watch` a job just to get the putted jobs.

## Statistics

**ElixirTalkd** accumulates various statistics at the server, tube and job level. Statistical details for a job can only be retrieved during the job's lifecycle. So let's create another job:

    [id: 27, tube: "default", state: "ready", pri: 0, age: 379859, delay: 0,
     ttr: 60, "time-left": 0, file: 0, reserves: 2, timeouts: 2, releases: 0,
     buries: 0, kicks: 0]

You can't access a deleted or not existed job's stats, or you'll only get a `:not_found`.

    iex(20)> ElixirTalk.stats_job(pid, 26)
    :not_found

You can also access a tube's statistics:

    iex(21)> ElixirTalk.stats_tube(pid, "default")
    [name: "default", "current-jobs-urgent": 19, "current-jobs-ready": 19,
     "current-jobs-reserved": 0, "current-jobs-delayed": 0,
     "current-jobs-buried": 0, "total-jobs": 37, "current-using": 1,
     "current-watching": 1, "current-waiting": 0, "cmd-delete": 18,
     "cmd-pause-tube": 0, pause: 0, "pause-time-left": 0]

Finally, there's an abundant amount of server-level statistics accessible via the Connection's stats method:

    iex(22)> ElixirTalk.stats(pid)
    ["current-jobs-urgent": 22, "current-jobs-ready": 28,
     "current-jobs-reserved": 0, "current-jobs-delayed": 0,
     "current-jobs-buried": 0, "cmd-put": 49, "cmd-peek": 0, "cmd-peek-ready": 13,
     "cmd-peek-delayed": 4, "cmd-peek-buried": 4, "cmd-reserve": 56,
     "cmd-reserve-with-timeout": 41, "cmd-delete": 22, "cmd-release": 0,
     "cmd-use": 14, "cmd-watch": 7, "cmd-ignore": 8, "cmd-bury": 0, "cmd-kick": 0,
     "cmd-touch": 0, "cmd-stats": 21, "cmd-stats-job": 8, "cmd-stats-tube": 13,
     "cmd-list-tubes": 16, "cmd-list-tube-used": 17, "cmd-list-tubes-watched": 20,
     "cmd-pause-tube": 0, "job-timeouts": 47, "total-jobs": 47,
     "max-job-size": 65535, "current-tubes": 3, "current-connections": 1,
     "current-producers": 0, "current-workers": 0, "current-waiting": 0,
     "total-connections": 90, pid: 17492, version: 1.8, "rusage-utime": 15.396318,
     "rusage-stime": 2312.522858, uptime: 454596, "binlog-oldest-index": 0,
     "binlog-current-index": 0, "binlog-records-migrated": 0,
     "binlog-records-written": 0, "binlog-max-size": 10485760]


## Test

If you want to run the TestCase, you set the correct Beanstalkd IP and Port
in [test/elixir_talk_test.exs]("http://www.github.com/jsvisa/elixit_talk/test/elixir_talk_test.exs"),
also you should set a hostname `my.beanstalkd.com` with the provided ip in */etc/hosts*