community_theatre v0.1.1 CommunityTheatre

Community theatre is similar but opposite to the 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:

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
}}

Link to this section Summary

Functions

Publish a message to subscribed clients.

Publishes the provided payload to the topic.

Subscribe to updates from the given topic without any rate limiting.

Subscribe to updates from the given topic.

Subscribe to updates from the given topic.

Link to this section Functions

Link to this function

publish(message)

publish(CommunityTheatre.Message.t()) :: :ok

Publish a message to subscribed clients.

Link to this function

publish(topic, payload)

publish(atom(), any()) :: :ok

Publishes the provided payload to the topic.

Wraps the topic and payload in a Message.t() and calls publish/1.

Link to this function

subscribe(topic)

subscribe(atom()) :: :ok | {:error, any()}

Subscribe to updates from the given topic without any rate limiting.

Calling this function subscribes the calling process to updates to the specified topic. No rate limiting takes place.

Params:

  • topic an artibrary name for a stream of data being proccessed in the system.
Link to this function

subscribe(topic, update_frequency)

subscribe(atom(), non_neg_integer()) :: :ok | {:error, any()}

Subscribe to updates from the given topic.

Calling this function subscribes the calling process to updates to the specified topic. If updates are received faster than the specified frequency then they are dropped.

Params:

  • topic an artibrary name for a stream of data being proccessed in the system.
  • update_frequency (in Hz) how often you would like to receive updates.
Link to this function

subscribe(topic, update_frequency, rate_limiter)

subscribe(atom(), non_neg_integer(), atom()) :: :ok

Subscribe to updates from the given topic.

Calling this function subscribes the calling process to updates to the current topic.

Params:

  • topic an artibrary name for a stream of data being proccessed in the system.
  • update_frequency (in Hz) how often you would like to receive updates.
  • rate_limiter the name of a module which implements the CommunityTheatre.RateLimiter behaviour, which specifies what to do when data arrives faster than you are requesting.