README.md

# CommunityTheatre

Community theatre is similar but opposite to the
[broadway](https://hex.pm/packages/broadway) package.  It's designed to handle
ingesting data from sources at various update frequencies and emit them again to
consumers at a constrained rate.  Particularly useful for devices of constrained
resources.

## Usage

Any Erlang term can be published to arbitrary topics at any rate:

```elixir
for bottle_count <- Enum.reverse(0..99) do
  CommunityTheatre.publish(:bottles_of_beer_on_the_wall, bottle_count)
  Process.sleep(100)
end
```

However subscribers will only receive updates at the frequency they specify.
You can implement the `CommunityTheatre.RateLimiter` behaviour to specify how to
deal with extra methods.  This package includes the `Drop` and `Average`
limiters.  `Drop` is used by default if none is specified.

    iex> CommunityTheatre.subscribe(:bottles_of_beer_on_the_wall, 0.3, CommunityTheatre.RateLimiter.Average)
    ...> for bottle_count <- Enum.reverse(0..99) do
    ...>   CommunityTheatre.publish(:bottles_of_beer_on_the_wall, bottle_count)
    ...>   Process.sleep(100)
    ...> end
    ...> flush
    {CommunityTheatre,
    %CommunityTheatre.Message{
      payload: 83,
      received_at: ~U[2020-04-10 04:31:58.215609Z],
      topic: :bottles_of_beer_on_the_wall
    }}
    {CommunityTheatre,
    %CommunityTheatre.Message{
      payload: 50,
      received_at: ~U[2020-04-10 04:32:01.548600Z],
      topic: :bottles_of_beer_on_the_wall
    }}
    {CommunityTheatre,
    %CommunityTheatre.Message{
      payload: 17,
      received_at: ~U[2020-04-10 04:32:04.881524Z],
      topic: :bottles_of_beer_on_the_wall
    }}

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `community_theatre` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:community_theatre, "~> 0.1.0"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/community_theatre](https://hexdocs.pm/community_theatre).