kevinoneill / wee-pub

A simple broadcast system for messages

WeePub

WeePub is a light weight publish/subscribe system built on the elixir Registry.

defmodule TestSubscriber do
  use WeePub.Subscriber

  subscribe %{id: id, age: age} = message, where: age > 16 and id != 1 do
    {"%{id: id, age: age} = message, where: age > 16 and id != 1", message}
  end

  subscribe %{id: id} = message, where: id == 1 do
    {"%{id: id} = message, where: id == 1", message}
  end

  subscribe(%{id: _} = message) do
    {"%{id: _} = message", message}
  end

  subscribe(message) do
    {"message", message}
  end

  def handle_call(:state, _caller, state) do
    {:reply, state, state}
  end

  def state do
    GenServer.call(TestSubscriber, :state)
  end
end

Features

• Broadcast messages
• Narrow cast messages to specific a topic
• Subscribe to Broadcast messages using match expressions
• Subscribe to Narrow cast messages using match expressions
• Subscriber implicit state handling
• Subscriber explicit state handling
• Allow generated GenServer methods to be overridden
• Specs for all interfaces
• Docs for all important methods

Summary

WeePub.Broadcaster

WeePub.Broadcaster has two simple methods, subscribe to register subscribers, and publish to publish messages.

Registration is handled automatically when WeePub.Subscriber is used but any GenServer can be registered to receive messages.

WeePub.Subscriber

By using WeePub.Subscriber your module will be created as a GenServer with default child_spec, start and init methods.

The subscribe macro will create a handle_cast method pattern matched to the subscription and will register the Module and pattern with WeePub.Broadcaster.

Like any pattern matching order of declaration is important.

subscribe any do … will intercept calls to more specific version e.g. subscribe %{id: _} … if higher up in the file.

Note: Messages are cast to subscribers, meaning there is no acknowledgement of receipt. This is not meant to be used as reliable delivery messaging system.

Installation

If available in Hex, the package can be installed by adding weepub to your list of dependencies in mix.exs:

def deps do
  [
    {:weepub, "~> 0.1.0"}
  ]
end

where: vs when

I would have liked not to have the where: keyword parameter and instead just used a when clause (which is what the where: parameter is transformed into). Unfortunately my conjuring of macro constructs failed to give me a reliable result.