View Source Solvent (solvent v0.2.0)

Solvent is an event bus built to be fast and easy-to-use.

Publish and subscribe to events here. You can either provide a function to be run, with subscribe/2 and subscribe/3, or subscribe a module using subscribe/1. See the docs for Solvent.Subscriber for more information on module subscribers.

iex> Solvent.subscribe("My first subscriber", ~r/.*/, fn _type, event_id ->
...>   {:ok, _event} = Solvent.EventStore.fetch(event_id)
...>
...>   # play with the event, and acknowledge it when you're done
...>
...>   Solvent.EventStore.ack(event_id, "My first subscriber")
...> end)
{:ok, "My first subscriber"}

It's important to observe that subscriber functions are given the identifier of an event, not the event itself. Also, note that we call Solvent.EventStore.ack/2 once we're done with the event, so that Solvent knows it can clean up the event from the store.

Tip

Use the Solvent.Subscriber module to make a subscriber that automatically acknowledges events, along with lots of other nice features.

Once you have a subscriber, publish an event. Data is optional, only a type is required. This can be any string. I would recommend the CloudEvents format, which starts with a reversed DNS name, and is dot-separated. This will help avoid collisions with events from other applications.

iex> Solvent.publish("io.github.cantido.myevent.published", id: "0b06bdb7-06a7-4df9-a825-1fd225ceea43")
{:ok, "0b06bdb7-06a7-4df9-a825-1fd225ceea43"}

Here you can also supply data for the event with the :data option.

iex> Solvent.publish("io.github.cantido.myevent.published", data: "Hello, world!", id: "d0f63676-b853-4f30-8bcf-ea10f2184556")
{:ok, "d0f63676-b853-4f30-8bcf-ea10f2184556"}

This will be available on the :data key of the event object you fetch from Solvent.EventStore. See the Solvent.Event docs for more information on what that struct contains.

Link to this section Summary

Functions

Publish an event to the event bus, triggering all subscriber functions.

Subscribe to the event bus.

Execute a function when an event is published.

Remove a subscriber.

Link to this section Functions

Link to this function

publish(type, opts \\ [])

View Source

Publish an event to the event bus, triggering all subscriber functions.

Only a type (AKA "topic") is required. All other fields can be supplied using the options. See Solvent.Event for details on what that struct contains. All values given as options are inserted into the event struct.

ID values are version 4 UUIDs by default, and you don't need to provide them.

examples

Examples

Solvent.publish("io.github.cantido.documentation.read")
{:ok, "some-random-uuid"}

iex> Solvent.publish(
...>   "io.github.cantido.documentation.read",
...>   id: "read-docs-id",
...>   datacontenttype: "application/json",
...>   data: ~s({"hello":"world"})
...> )
{:ok, "read-docs-id"}
Link to this function

subscribe(arg1, arg2 \\ [])

View Source

Subscribe to the event bus.

When the first argument is a module, the module is subscribed to the event bus, and the second argument is expected to be a list of options, if it is provided at all. See Solvent.Subscriber for details.

If the first argument is a string or regex, then the second argument must be a function, and the function behaves exactly like subscribe/3 but with an auto-generated ID.

Link to this function

subscribe(id, match_type, fun)

View Source

Execute a function when an event is published.

The match_type argument can be either a string or a regular expression. It is matched with an event's type using the Kernel.=~/2 operator.

The function argument will be given the ID of the event. You must fetch the event from Solvent.EventStore if you wish to use it.

The ID is optional, and defaults to a version 4 UUID.

iex> Solvent.subscribe("My subscriber", "idsubscriber.event.published", fn event_id ->
...>   {:ok, _event} = Solvent.EventStore.fetch(event_id)
...>   # Use the event, then delete it
...>   Solvent.EventStore.delete(event_id)
...> end)
{:ok, "My subscriber"}

Remove a subscriber.