registry (ex_stdlib v0.3.0)
View SourceA local, decentralized and scalable key-value process storage.
It allows developers to lookup one or more processes with a given key. If the registry has unique keys, a key points to 0 or 1 process. If the registry allows duplicate keys, a single key may point to any number of processes. In both cases, different keys could identify the same process.
Each entry in the registry is associated to the process that has registered the key. If the process crashes, the keys associated to that process are automatically removed. All key comparisons in the registry are done using the match operation (=:=).
The registry can be used for different purposes, such as name lookups (using the via option), storing properties, custom dispatching rules, or a pubsub implementation.
Using in via
Once the registry is started with a given name using start_link/1, it can be used to register and access named processes using the {via, registry, {registry_name, key}} tuple, or {via, registry, {registry_name, key, value}} to also store a value:
{ok, _} = registry:start_link([{keys, unique}, {name, my_registry}]),
Name = {via, registry, {my_registry, "agent"}},
{ok, _} = agent:start_link(fun() -> 0 end, [{name, Name}]),
0 = agent:get(Name, fun(State) -> State end).Using as a dispatcher
Registry has a dispatch mechanism that allows developers to implement custom dispatch logic triggered from the caller. For example:
{ok, _} = registry:start_link([{keys, duplicate}, {name, dispatcher_test}]),
{ok, _} = registry:register(dispatcher_test, "hello", {io, format}),
registry:dispatch(dispatcher_test, "hello", fun(Entries) ->
[apply(M, F, [Pid, "Hello ~p~n"]) || {Pid, {M, F}} <- Entries]
end).Summary
Functions
Invokes the callback with all entries under the given key.
Returns all keys registered by the given process.
Looks up processes registered under the given key.
Registers the current process under the given key with an associated value.
Registers Pid under a {Registry, Key} or {Registry, Key, Value} name.
Sends Msg to the process registered under a {via, registry, Name} name. Exits with {badarg, {Name, Msg}} if no process is registered.
Starts a registry with the given options.
Unregisters the current process from the given key.
Unregisters a {via, registry, Name} name.
Updates the value for the given key for the current process.
Returns the values registered by the given process under the given key.
Deprecated: use {via, registry, Name} or register_name/2.
Deprecated: use send/2.
Deprecated: use unregister_name/1.
Deprecated: use whereis_name/1.
Returns the process registered under a {via, registry, Name} name, or undefined.
Types
Functions
-spec dispatch(registry(), key(), dispatcher()) -> ok.
Invokes the callback with all entries under the given key.
The callback receives a list of {Pid, Value} tuples. If there are no entries for the given key, the callback is not invoked.
-spec dispatch(registry(), key(), dispatcher(), list()) -> ok.
Returns all keys registered by the given process.
Looks up processes registered under the given key.
Returns a list of {Pid, Value} tuples. For unique registries, the list will have at most one element.
Registers the current process under the given key with an associated value.
Returns {ok, Owner} on success where Owner is the registry process PID. Returns {error, {already_registered, Pid}} if the key is already taken in a unique registry.
Registers Pid under a {Registry, Key} or {Registry, Key, Value} name.
This is the {via, registry, Name} callback used by OTP behaviours (gen_server, gen_statem, supervisor...). The value defaults to nil. Only unique registries are supported.
Sends Msg to the process registered under a {via, registry, Name} name. Exits with {badarg, {Name, Msg}} if no process is registered.
Starts a registry with the given options.
The supported options are:
- {keys, Keys} - either unique or duplicate. Defaults to unique. - {name, Name} - the name of the registry. Required.
If keys is unique, a key can only be registered by one process. If keys is duplicate, multiple processes can register under the same key.
Returns {ok, Pid} on success.
Unregisters the current process from the given key.
Always returns ok.
-spec unregister_name(via_name()) -> ok.
Unregisters a {via, registry, Name} name.
Updates the value for the given key for the current process.
Returns {NewValue, OldValue} on success or error if there is no such key registered by the current process.
Only works with unique registries.
Returns the values registered by the given process under the given key.
For unique registries, returns a list with at most one element. For duplicate registries, returns a list with zero or more elements.
Deprecated: use {via, registry, Name} or register_name/2.
Deprecated: use send/2.
Deprecated: use unregister_name/1.
Deprecated: use whereis_name/1.
Returns the process registered under a {via, registry, Name} name, or undefined.