Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

984 lines (314 sloc) 23.9 kB

Module gproc

Module gproc

Extended process registry.

Behaviours: gen_server.

Authors: Ulf Wiger (ulf.wiger@erlang-consulting.com).

Description

This module implements an extended process registry

For a detailed description, see erlang07-wiger.pdf.

Type and scope for registration and lookup:

Data Types

context()

context() = {scope(), type()} | type()

{'all','all'} is the default

headpat()

headpat() = {keypat(), pidpat(), ValPat}

key()

key() = {type(), scope(), any()}

keypat()

keypat() = {sel_type() | sel_var(), l | g | sel_var(), any()}

pidpat()

pidpat() = pid() | sel_var()

sel_var() = DollarVar | '_'.

scope()

scope() = l | g

l = local registration; g = global registration

Type and scope for select(), qlc() and stepping:

sel_pattern()

sel_pattern() = [{headpat(), Guards, Prod}]

sel_scope()

sel_scope() = scope | all | global | local

sel_type()

sel_type() = type() | names | props | counters | aggr_counters

type()

type() = n | p | c | a

n = name; p = property; c = counter; a = aggregate_counter

Function Index

add_global_aggr_counter/1Registers a global (unique) aggregated counter.
add_global_counter/2Registers a global (non-unique) counter.
add_global_name/1Registers a global (unique) name.
add_global_property/2Registers a global (non-unique) property.
add_local_aggr_counter/1Registers a local (unique) aggregated counter.
add_local_counter/2Registers a local (non-unique) counter.
add_local_name/1Registers a local (unique) name.
add_local_property/2Registers a local (non-unique) property.
audit_process/1
await/1Equivalent to await(Key, infinity).
await/2Wait for a local name to be registered.
cancel_wait/2
default/1
first/1Behaves as ets:first(Tab) for a given type of registration object.
get_value/1Read the value stored with a key registered to the current process.
give_away/2Atomically transfers the key From to the process identified by To.
info/1Similar to process_info(Pid) but with additional gproc info.
info/2Similar to process_info(Pid, Item), but with additional gproc info.
last/1Behaves as ets:last(Tab) for a given type of registration object.
lookup_global_aggr_counter/1Lookup a global (unique) aggregated counter and returns its value.
lookup_global_counters/1Look up all global (non-unique) instances of a given Counter.
lookup_global_name/1Lookup a global unique name.
lookup_global_properties/1Look up all global (non-unique) instances of a given Property.
lookup_local_aggr_counter/1Lookup a local (unique) aggregated counter and returns its value.
lookup_local_counters/1Look up all local (non-unique) instances of a given Counter.
lookup_local_name/1Lookup a local unique name.
lookup_local_properties/1Look up all local (non-unique) instances of a given Property.
lookup_pid/1Lookup the Pid stored with a key.
lookup_pids/1Returns a list of pids with the published key Key.
lookup_value/1Lookup the value stored with a key.
lookup_values/1Retrieve the {Pid,Value} pairs corresponding to Key.
mreg/3Register multiple {Key,Value} pairs of a given type and scope.
nb_wait/1Wait for a local name to be registered.
next/2Behaves as ets:next(Tab,Key) for a given type of registration object.
prev/2Behaves as ets:prev(Tab,Key) for a given type of registration object.
reg/1Equivalent to reg(Key, default(Key)).
reg/2Register a name or property for the current process.
select/1Equivalent to select(all, Pat).
select/2Perform a select operation on the process registry.
select/3Like select/2 but returns Limit objects at a time.
send/2Sends a message to the process, or processes, corresponding to Key.
set_value/2Sets the value of the registeration entry given by Key.
start_link/0Starts the gproc server.
table/1Equivalent to table(Context, []).
table/2QLC table generator for the gproc registry.
unreg/1Unregister a name or property.
unregister_name/1Equivalent to unreg / 1.
update_counter/2Updates the counter registered as Key for the current process.
where/1Returns the pid registered as Key.
whereis_name/1Equivalent to where / 1.

Function Details

add_global_aggr_counter/1

add_global_aggr_counter(Name) -> any()

Equivalent to reg({a, g, Name}).

Registers a global (unique) aggregated counter.

add_global_counter/2

add_global_counter(Name, Initial) -> any()

Registers a global (non-unique) counter. @equiv reg({c,g,Name},Value)

add_global_name/1

add_global_name(Name) -> any()

Registers a global (unique) name. @equiv reg({n,g,Name})

add_global_property/2

add_global_property(Name, Value) -> any()

Registers a global (non-unique) property. @equiv reg({p,g,Name},Value)

add_local_aggr_counter/1

add_local_aggr_counter(Name) -> any()

Equivalent to reg({a, l, Name}).

Registers a local (unique) aggregated counter.

add_local_counter/2

add_local_counter(Name, Initial) -> any()

Registers a local (non-unique) counter. @equiv reg({c,l,Name},Value)

add_local_name/1

add_local_name(Name) -> any()

Registers a local (unique) name. @equiv reg({n,l,Name})

add_local_property/2

add_local_property(Name, Value) -> any()

Registers a local (non-unique) property. @equiv reg({p,l,Name},Value)

audit_process/1

audit_process(Pid::pid()) -> ok



await/1

await(Key::key()) -> {pid(), Value}



Equivalent to await(Key, infinity).

await/2

await(Key::key(), Timeout) -> {pid(), Value}
  • Timeout = integer() | infinity

Wait for a local name to be registered. The function raises an exception if the timeout expires. Timeout must be either an interger > 0 or 'infinity'. A small optimization: we first perform a lookup, to see if the name is already registered. This way, the cost of the operation will be roughly the same as of where/1 in the case where the name is already registered (the difference: await/2 also returns the value).

cancel_wait/2

cancel_wait(Key, Ref) -> any()

default/1

default(X1) -> any()

first/1

first(Context::context()) -> key() | '$end_of_table'



Behaves as ets:first(Tab) for a given type of registration object.

See http://www.erlang.org/doc/man/ets.html#first-1. The registry behaves as an ordered_set table.

get_value/1

get_value(Key) -> Value



Read the value stored with a key registered to the current process.

If no such key is registered to the current process, this function exits.

give_away/2

give_away(From::key(), To::pid() | key()) -> undefined | pid()



Atomically transfers the key From to the process identified by To.

This function transfers any gproc key (name, property, counter, aggr. counter)
from one process to another, and returns the pid of the new owner.

To must be either a pid or a unique name (name or aggregated counter), but does not necessarily have to resolve to an existing process. If there is no process registered with the To key, give_away/2 returns undefined, and the From key is effectively unregistered.

It is allowed to give away a key to oneself, but of course, this operation
will have no effect.

Fails with badarg if the calling process does not have a From key registered.

info/1

info(Pid::pid()) -> ProcessInfo
  • ProcessInfo = [{gproc, [{Key, Value}]} | ProcessInfo]

Similar to process_info(Pid) but with additional gproc info.

Returns the same information as process_info(Pid), but with the addition of a gproc information item, containing the {Key,Value} pairs registered to the process.

info/2

info(Pid::pid(), Item::atom()) -> {Item, Info}



Similar to process_info(Pid, Item), but with additional gproc info.

For Item = gproc, this function returns a list of {Key, Value} pairs registered to the process Pid. For other values of Item, it returns the same as http://www.erlang.org/doc/man/erlang.html#process_info-2.

last/1

last(Context::context()) -> key() | '$end_of_table'



Behaves as ets:last(Tab) for a given type of registration object.

See http://www.erlang.org/doc/man/ets.html#last-1. The registry behaves as an ordered_set table.

lookup_global_aggr_counter/1

lookup_global_aggr_counter(Name::any()) -> integer()



Equivalent to where({a, g, Name}).

Lookup a global (unique) aggregated counter and returns its value. Fails if there is no such object.

lookup_global_counters/1

lookup_global_counters(Counter::any()) -> [{pid(), Value::integer()}]



Equivalent to lookup_values({c, g, Counter}).

Look up all global (non-unique) instances of a given Counter. Returns a list of {Pid, Value} tuples for all matching objects.

lookup_global_name/1

lookup_global_name(Name::any()) -> pid()



Equivalent to where({n, g, Name}).

Lookup a global unique name. Fails if there is no such name.

lookup_global_properties/1

lookup_global_properties(Property::any()) -> [{pid(), Value}]



Equivalent to lookup_values({p, g, Property}).

Look up all global (non-unique) instances of a given Property. Returns a list of {Pid, Value} tuples for all matching objects.

lookup_local_aggr_counter/1

lookup_local_aggr_counter(Name::any()) -> integer()



Equivalent to where({a, l, Name}).

Lookup a local (unique) aggregated counter and returns its value. Fails if there is no such object.

lookup_local_counters/1

lookup_local_counters(Counter::any()) -> [{pid(), Value::integer()}]



Equivalent to lookup_values({c, l, Counter}).

Look up all local (non-unique) instances of a given Counter. Returns a list of {Pid, Value} tuples for all matching objects.

lookup_local_name/1

lookup_local_name(Name::any()) -> pid()



Equivalent to where({n, l, Name}).

Lookup a local unique name. Fails if there is no such name.

lookup_local_properties/1

lookup_local_properties(Property::any()) -> [{pid(), Value}]



Equivalent to lookup_values({p, l, Property}).

Look up all local (non-unique) instances of a given Property. Returns a list of {Pid, Value} tuples for all matching objects.

lookup_pid/1

lookup_pid(Key) -> Pid



Lookup the Pid stored with a key.

lookup_pids/1

lookup_pids(Key::key()) -> [pid()]



Returns a list of pids with the published key Key

If the type of registration entry is either name or aggregated counter, this function will return either an empty list, or a list of one pid. For non-unique types, the return value can be a list of any length.

lookup_value/1

lookup_value(Key) -> Value



Lookup the value stored with a key.

lookup_values/1

lookup_values(Key::key()) -> [{pid(), Value}]



Retrieve the {Pid,Value} pairs corresponding to Key.

Key refer to any type of registry object. If it refers to a unique object, the list will be of length 0 or 1. If it refers to a non-unique object, the return value can be a list of any length.

mreg/3

mreg(T::type(), X2::scope(), KVL::[{Key::any(), Value::any()}]) -> true



Register multiple {Key,Value} pairs of a given type and scope.

This function is more efficient than calling reg/2 repeatedly.

nb_wait/1

nb_wait(Key::key()) -> Ref



Wait for a local name to be registered. The caller can expect to receive a message, {gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.

next/2

next(Context::context(), Key::key()) -> key() | '$end_of_table'



Behaves as ets:next(Tab,Key) for a given type of registration object.

See http://www.erlang.org/doc/man/ets.html#next-2. The registry behaves as an ordered_set table.

prev/2

prev(Context::context(), Key::key()) -> key() | '$end_of_table'



Behaves as ets:prev(Tab,Key) for a given type of registration object.

See http://www.erlang.org/doc/man/ets.html#prev-2. The registry behaves as an ordered_set table.

reg/1

reg(Key::key()) -> true



Equivalent to reg(Key, default(Key)).

reg/2

reg(Key::key(), Value) -> true



Register a name or property for the current process

select/1

select(Pat::select_pattern()) -> [sel_object()]



Equivalent to select(all, Pat).

select/2

select(Context::context(), Pat::sel_pattern()) -> [{Key, Pid, Value}]



Perform a select operation on the process registry.

The physical representation in the registry may differ from the above, but the select patterns are transformed appropriately.

select/3

select(Context::context(), Pat::sel_patten(), Limit::integer()) -> [{Key, Pid, Value}]



Like select/2 but returns Limit objects at a time.

See http://www.erlang.org/doc/man/ets.html#select-3.

send/2

send(Key::key(), Msg::any()) -> Msg



Sends a message to the process, or processes, corresponding to Key.

If Key belongs to a unique object (name or aggregated counter), this function will send a message to the corresponding process, or fail if there is no such process. If Key is for a non-unique object type (counter or property), Msg will be send to all processes that have such an object.

set_value/2

set_value(Key::key(), Value) -> true



Sets the value of the registeration entry given by Key

Key is assumed to exist and belong to the calling process.
If it doesn't, this function will exit.

Value can be any term, unless the object is a counter, in which case it must be an integer.

start_link/0

start_link() -> {ok, pid()}



Starts the gproc server.

This function is intended to be called from gproc_sup, as part of starting the gproc application.

table/1

table(Context::context()) -> any()



Equivalent to table(Context, []).

table/2

table(Context::context(), Opts) -> any()



QLC table generator for the gproc registry. Context specifies which subset of the registry should be queried. See http://www.erlang.org/doc/man/qlc.html.

unreg/1

unreg(Key::key()) -> true



Unregister a name or property.

unregister_name/1

unregister_name(Key) -> any()

Equivalent to unreg / 1.

update_counter/2

update_counter(Key::key(), Incr::integer()) -> integer()



Updates the counter registered as Key for the current process.

This function works like ets:update_counter/3 (see http://www.erlang.org/doc/man/ets.html#update_counter-3), but will fail if the type of object referred to by Key is not a counter.

where/1

where(Key::key()) -> pid()



Returns the pid registered as Key

The type of registration entry must be either name or aggregated counter. Otherwise this function will exit. Use lookup_pids/1 in these cases.

whereis_name/1

whereis_name(Key) -> any()

Equivalent to where / 1.

Jump to Line
Something went wrong with that request. Please try again.