leaderboard v0.2.0 Leaderboard

The implementation of leaderboard (rank table) based on ETS tables.

It associates a key with a score and orders these records according to the score. The score can be any term.

The leaderboard provides an API for inserting and deleting records as well as functions for reading records in defined order.

Usage

Once the leaderboard is started using Leaderboard.start_link/2 with a unique name of the table, it can be used to store and read records:

{:ok, _pid} = Leaderboard.start_link(Leaderboad.Score)
Leaderboard.insert(Leaderboard.Score, 1, "key1")
Leaderboard.insert(Leaderboard.Score, 3, "key3")
Leaderboard.insert(Leaderboard.Score, 2, "key2")
Leaderboard.select(Leaderboard.Score, :descend, 2)
#=> [{3, "key3"}, {2, "key2"}]
Leaderboard.select(Leaderboard.Score, :ascend, 2)
#=> [{1, "key1"}, {2, "key2"}]

Usually, the leaderboard is started as a part of a supervision tree:

worker(Leaderboard, [Leaderboard.Score])

When a key is already present and it is inserted again, the score associated with the given key gets updated (insert/3 works as update function as well).

Note that all the write operations such as insert/3 and delete/2 (as opposed to the read operations) are serialised via the GenServer process.

Summary

Types

Key associated with a score

The max number of records to return (or all of them)

Match specification

Return values of start* functions

Options used by the start* functions

Order of returned records

Score and key together

Score of a given key

Name of the leaderboard

Functions

Deletes a record based on the key

Deletes all the records

Inserts a new record or updates the score of an existing key

Returns a score associated with a key

Returns all the values as defined in match_spec

Behaves the same as match/3, but also has limit that defines the max number of returned values

Returns all the records ordered in specified order

Behaves the same as select/2, but also has limit that defines the max number of returned records

Returns the number of records in the table

Starts GenServer process without links

Starts GenServer process with link to the current process

Types

key()
key() :: term

Key associated with a score

limit()
limit() :: pos_integer | :all

The max number of records to return (or all of them)

match_spec()
match_spec() :: :ets.match_spec

Match specification

on_start()
on_start() :: GenServer.on_start

Return values of start* functions

options()
options() :: GenServer.options

Options used by the start* functions

order()
order() :: :ascend | :descend

Order of returned records

record()
record() :: {score, key}

Score and key together

score()
score() :: term

Score of a given key

table_name()
table_name() :: atom

Name of the leaderboard

Functions

delete(table_name, key, timeout \\ 5000)
delete(table_name, key, timeout) :: boolean

Deletes a record based on the key.

delete_all(table_name, timeout \\ 5000)
delete_all(table_name, timeout) :: :ok

Deletes all the records.

insert(table_name, score, key, timeout \\ 5000)
insert(table_name, score, key, timeout) :: :ok

Inserts a new record or updates the score of an existing key.

lookup(table_name, key)
lookup(table_name, key) :: score | nil

Returns a score associated with a key.

match(table_name, match_spec, order)
match(table_name, match_spec, order) :: [term]

Returns all the values as defined in match_spec.

The returned values don’t have to be records in form of {score, key}. The values are matched using the match_spec and they are ordered in specified order.

For example, the match_spec to return all the records is [{{:"$1"}, [], [:"$1"]}].

match(table_name, match_spec, order, limit)
match(table_name, match_spec, order, limit) :: [term]

Behaves the same as match/3, but also has limit that defines the max number of returned values.

select(table_name, order)
select(table_name, order) :: [record]

Returns all the records ordered in specified order.

select(table_name, order, limit)
select(table_name, order, limit) :: [record]

Behaves the same as select/2, but also has limit that defines the max number of returned records.

size(table_name)
size(table_name) :: non_neg_integer

Returns the number of records in the table.

start(table_name, options \\ [])

Starts GenServer process without links.

start_link(table_name, options \\ [])
start_link(table_name, options) :: on_start

Starts GenServer process with link to the current process.

The table_name must be an atom, based on which ETS leaderboard tables are created. The GenServer process is the owner of the ETS tables.