PropertyTable (property_table v0.1.0) View Source

In-memory key-value store with subscriptions

PropertyTable makes it easy to set up a key-value store where users can subscribe to changes based on patterns. PropertyTable refers to keys as properties. Properties have values and are timestamped as to when they received that value. Subscriptions make this library feel similar to Publish-Subscribe. Events, though, are only for changes to properties.

PropertyTable is useful when you want to expose a decent amount of state and let consumers pick and choose what parts interest them.

PropertyTable consumers express their interest in properties using "patterns". A pattern could be as simple as the property of interest or it could contain wildcards. This allows one to create hierarchical key-value stores, map-based stores, or just simple key-value stores with notifications.

PropertyTable is not persistent. Keys and values are backed by ETS.

Link to this section Summary

Types

PropertyTable configuration options

Properties

A table_id identifies a group of properties

Functions

Returns a specification to start a property_table under a supervisor. See Supervisor.

Delete the specified property

Clear out all properties that match a pattern

Fetch a property with the time that it was set

Get the current value of a property

Get all properties

Get a list of all properties matching the specified property pattern

Update a property and notify listeners

Start a PropertyTable's supervision tree

Subscribe to receive events

Stop subscribing to a property

Link to this section Types

Specs

option() ::
  {:name, table_id()}
  | {:properties, [property_value()]}
  | {:tuple_events, boolean()}

PropertyTable configuration options

See start_link/2 for usage.

Specs

pattern() :: any()

Specs

property() :: any()

Properties

Specs

property_value() :: {property(), value()}

Specs

table_id() :: atom()

A table_id identifies a group of properties

Specs

value() :: any()

Link to this section Functions

Specs

child_spec(keyword()) :: Supervisor.child_spec()

Returns a specification to start a property_table under a supervisor. See Supervisor.

Specs

clear(table_id(), property()) :: :ok

Delete the specified property

Link to this function

clear_all(table, pattern)

View Source

Specs

clear_all(table_id(), pattern()) :: :ok

Clear out all properties that match a pattern

Link to this function

fetch_with_timestamp(table, property)

View Source

Specs

fetch_with_timestamp(table_id(), property()) ::
  {:ok, value(), integer()} | :error

Fetch a property with the time that it was set

Timestamps come from System.monotonic_time()

Link to this function

get(table, property, default \\ nil)

View Source

Specs

get(table_id(), property(), value()) :: value()

Get the current value of a property

Specs

get_all(table_id()) :: [{property(), value()}]

Get all properties

This function might return a really long list so it's mainly intended for debug or convenience when you know that the table only contains a few properties.

Specs

match(table_id(), pattern()) :: [{property(), value()}]

Get a list of all properties matching the specified property pattern

Link to this function

put(table, property, value)

View Source

Specs

put(table_id(), property(), value()) :: :ok | {:error, Exception.t()}

Update a property and notify listeners

Specs

start_link([option()]) :: Supervisor.on_start()

Start a PropertyTable's supervision tree

To create a PropertyTable for your application or library, add the following child_spec to one of your supervision trees:

{PropertyTable, name: MyTableName}

The :name option is required. All calls to PropertyTable will need to know it and the process will be registered under than name so be sure it's unique.

Additional options are:

  • :properties - a list of {property, value} tuples to initially populate the PropertyTable
  • :matcher - set the format for how properties and how they should be matched for triggering events. See PropertyTable.Matcher.
  • :tuple_events - set to true for change events to be in the old tuple format. This is not recommended for new code and hopefully will be removed in the future.
Link to this function

subscribe(table, pattern)

View Source

Specs

subscribe(table_id(), pattern()) :: :ok

Subscribe to receive events

Link to this function

unsubscribe(table, pattern)

View Source

Specs

unsubscribe(table_id(), pattern()) :: :ok

Stop subscribing to a property