Flub is a pub-sub application intended to simplify larger applications.

Even in Elixir and OTP applications, close coupling modules can lead you into dark places. When one process publishes and another subscribes, neither needs to be specifically aware of the other. Additionally, extending the functionality of existing applications is much easier when new modules can just hook into existing published event streams.

Examples:

Basic subscription

    # subscriber pid:
    iex> Flub.sub(:trigger_channel)

    # publishing pid:
    iex> Flub.pub(:new_trigger, :trigger_channel)

    # subscriber pid:
    iex> flush
    :ok
    %Flub.Message{channel: :trigger_channel, data: :new_trigger,
      node: :nonode@nohost}

Pattern Matching (data, not channels)

The p/1 macro creates filter lambdas by expanding a case statement. Requesting a filter prevents non-matching data from being sent to the subscriber. Any lambda which accepts the published data, and returns true|false can be used as a filter.

    # subscriber pid.  Note channel is a 2-tuple in this example.
    iex> Flub.sub({Worker, 1}, filter: p(%Worker.CompletionIndication{}))

    # publisher pid:
    iex> Flub.pub(%OtherIndication{}, {Worker, 1})) # <= subscriber won't receive
    iex> Flub.pub(%Worker.CompletionIndication{task_id: 5}, {Worker, 1})

    # subscriber pid:

    iex> flush
    :ok
    %Flub.Message{channel: {Worker, 1},
                  data: %WorkerCompletionIndication{task_id: 5},
                  node: :nonode@nohost}

Publish Mapping

By specifying a :mapper lambda, a subscriber can request published messages be transformed before being sent, or prevent their arrival entirely by returning the special value Flub.cancel_pub

    # subscriber pid:
    iex> Flub.sub(:test_chan, mapper: fn %Flub.Message{data: :fake} -> Flub.cancel_pub
                                         %Flub.Message{data: :real} -> {42, :real}
                                      end)
    # publisher pid:
    iex> Flub.pub(:fake, :test_chan)
    iex> Flub.pub(:real, :test_chan)

    # subscriber_pid:
    iex> flush
    :ok
    {42, real}  #Note: There is no %Flub.Message{} struct wrapping the data.

Cross Node Subscription

Subscribers can request to listen for events originating on a specfic remote node.

    # subscriber pid:
    iex> node()
    :this_node@my-host
    iex> Flub.sub("a channel", node: :other_node@their-host)

    # publisher (on :other_node@their-host)
    Flub.pub({:new_data, 12}, "a channel")

    # subscriber:
    iex> flush
    :ok
    %Flub.Message{channel: "a channel", data: {:new_data, 12}, node: :other_node@their-host}

Global Subscription

Alternately, a subscriber can elect to receive all messages published to a channel, regardless of the originating node:

iex> Flub.sub("important channel", node: :global)
:ok