Overview

Module gproc

• Description
• Data Types
• Function Index
• Function Details

Behaviours: gen_server.

Authors: Ulf Wiger (ulf@wiger.net).

Description

Extended process registry This module implements an extended process registry

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

NOTE: The functions in the Gproc API expect the Gproc application to be running.

Tuning Gproc performance

Gproc relies on a central server and an ordered-set ets table. Effort is made to perform as much work as possible in the client without sacrificing consistency. A few things can be tuned by setting the following application environment variables in the top application of gproc (usually gproc):

Data Types

attr()

attr() = {atom(), any()}

attrs()

attrs() = [attr()]

context()

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

ctr_incr()

ctr_incr() = integer()

ctr_setval()

ctr_setval() = integer()

ctr_thr()

ctr_thr() = integer()

ctr_update()

ctr_update() = ctr_incr() | {ctr_incr(), ctr_thr(), ctr_setval()}

headpat()

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

increment()

increment() = ctr_incr() | ctr_update() | [ctr_update()]

key()

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

keypat()

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

monitor_type()

monitor_type() = info | standby | follow

pidpat()

pidpat() = pid() | sel_var()

reg_id()

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

scope()

scope() = l | g

sel_context()

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

sel_pattern()

sel_pattern() = [{headpat(), list(), list()}]

sel_scope()

sel_scope() = scope | all | global | local

sel_type()

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

sel_var()

sel_var() = '_' | atom()

type()

type() = n | p | c | a | r | rc

unique_id()

unique_id() = {n | a, scope(), any()}

value()

value() = any()

Function Index

Function Details

add_global_aggr_counter/1

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

Registers a global (unique) aggregated counter.

add_global_counter/2

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

add_global_name/1

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

add_global_property/2

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

add_local_aggr_counter/1

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

Registers a local (unique) aggregated counter.

add_local_counter/2

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

add_local_name/1

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

add_local_property/2

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

add_shared_local_counter/2

Equivalent to reg_shared({c, l, Name}, Value).

Registers a local shared (unique) counter.

audit_process/1

await/1

Equivalent to await(Key, infinity).

await/2

Wait for a name or aggregated counter 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).

await/3

Wait for a name or aggregated counter to be registered on Node. This function works exactly like await/2, but queries a remote node instead. An exception is thrown if Node cannot be reached. If gproc is not running on a given node, this is treated the same as the node being down.

bcast/2

Equivalent to bcast(nodes(), Key, Msg).

bcast/3

Sends a message to processes corresponding to Key on Nodes.

See also: send/2.

cancel_wait/2

Cancels a previous call to nb_wait/1

cancel_wait/3

Cancels a previous call to nb_wait/2

cancel_wait_or_monitor/1

default/1

demonitor/2

Remove a monitor on a registered name This function is the reverse of monitor/1. It removes a monitor previously set on a unique name. This function always succeeds given legal input.

ensure_reg/1

Equivalent to ensure_reg(Key, default(Key), []).

ensure_reg/2

Equivalent to ensure_reg(Key, Value, []).

ensure_reg/3

Registers a new name or property unless such and entry (by key) has already been registered by the current process. If Key already exists, the entry will be updated with the given Value and Attrs.

ensure_reg_other/2

ensure_reg_other/3

Equivalent to ensure_reg_other(Key, Pid, Value, []).

ensure_reg_other/4

Register or update name or property to another process.

first/1

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

get_attribute/2

Get attribute value of Attr associated with Key for most likely Pid.

get_attribute/3

Get the attribute value of Attr associated with Key for process Pid.

get_attribute_shared/2

Get the attribute value of Attr associated with the shared Key.

get_attributes/1

Equivalent to get_attributes(Key, self()).

Get attributes associated with registration.

get_attributes/2

Returns the list of attributes associated with the registration.

get_env/3

Equivalent to get_env(Scope, App, Key, [app_env]).

get_env/4

Read an environment value, potentially cached as a gproc_env property.

This function first tries to read the value of a cached property, {p, Scope, {gproc_env, App, Key}}. If this fails, it will try the provided alternative strategy. Strategy is a list of alternatives, tried in order. Each alternative can be one of:

* app_env - try application:get_env(App, Key) * os_env - try os:getenv(ENV), where ENV is Key converted into an uppercase string * {os_env, ENV} - try os:getenv(ENV) * inherit - inherit the cached value, if any, held by the parent process. * {inherit, Pid} - inherit the cached value, if any, held by Pid. * {inherit, Id} - inherit the cached value, if any, held by the process registered in gproc as Id. * init_arg - try init:get_argument(Key); expects a single value, if any. * {mnesia, ActivityType, Oid, Pos} - try mnesia:activity(ActivityType, fun() -> mnesia:read(Oid) end); retrieve the value in position Pos if object found. * {default, Value} - set a default value to return once alternatives have been exhausted; if not set, undefined will be returned. * error - raise an exception, erlang:error(gproc_env, [App, Key, Scope]).

While any alternative can occur more than once, the only one that might make sense to use multiple times is {default, Value}.

The return value will be one of:

* The value of the first matching alternative, or error eception, whichever comes first * The last instance of {default, Value}, or undefined, if there is no matching alternative, default or error entry in the list.

get_set_env/3

Equivalent to get_set_env(Scope, App, Key, [app_env]).

get_set_env/4

Fetch and cache an environment value, if not already cached.

See also: get_env/4.

get_value/1

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

get_value/2

Reads the value stored with a key registered to the process Pid.

get_value_shared/1

Reads the value stored with a shared key.

give_away/2

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.

goodbye/0

Unregister all items of the calling process and inform gproc to forget about the calling process.

i/0

Similar to the built-in shell command i() but inserts information about names and properties registered in Gproc, where applicable.

info/1

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

info/2

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

last/1

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

lookup_global_aggr_counter/1

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

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

lookup_global_counters/1

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

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

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

lookup_global_properties/1

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_global_resources/1

Equivalent to lookup_values({r, g, Resource}).

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

lookup_local_aggr_counter/1

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

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

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

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

lookup_local_properties/1

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_local_resources/1

Equivalent to lookup_values({r, l, Resource}).

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

lookup_pid/1

Lookup the Pid stored with a key.

lookup_pids/1

Returns a list of pids with the published key Key

If the type of registration 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 the value stored with a key.

lookup_values/1

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

monitor/1

Equivalent to monitor(Key, info).

monitor/2

monitor a registered name monitor(Key, info) works much like erlang:monitor(process, Pid), but monitors a unique name registered via gproc. A message, {gproc, unreg, Ref, Key} will be sent to the requesting process, if the name is unregistered or the registered process dies. If there is a standby monitor (see below), a message {gproc, {failover, ToPid}, Ref, Key} is sent to all monitors. If the name is passed to another process using give_away/2, the event {gproc, {migrated, ToPid}, Ref, Key} is sent to all monitors.

monitor(Key, standby) sets up the monitoring process as a standby for the registered name. If the registered process dies, the first standby process inherits the name, and a message {gproc, {failover, ToPid}, Ref, Key} is sent to all monitors, including the one that inherited the name.

If the name is not yet registered, the unreg event is sent immediately. If the calling process in this case tried to start a standby monitoring, it receives the registered name and the failover event immediately.

mreg/3

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

munreg/3

Unregister multiple Key items of a given type and scope.

nb_wait/1

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

nb_wait/2

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

next/2

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

prev/2

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

reg/1

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

reg/2

Register a name or property for the current process

reg/3

Register a name or property for the current process Attrs (default: []) can be inspected using get_attribute/2.

The structure of Key is {Type, Context, Name}, where:

* Context :: l | g - l means 'local' context; g means 'global' * Type :: p | n | c | a | r | rc specifies the type of entry

The semantics of the different types:

* p - 'property', is non-unique, i.e. different processes can each register a property with the same name. * n - 'name, is unique within the given context (local or global). * c - 'counter', is similar to a property, but has a numeric value and behaves roughly as an ets counter (see update_counter/2.) * a - 'aggregated counter', is automatically updated by gproc, and reflects the sum of all counter objects with the same name in the given scope. The initial value for an aggregated counter must be undefined. * r - 'resource property', behaves like a property, but can be tracked with a 'resource counter'. Note that using an rc wildcard name pattern (see below) for a resource property is not allowed. * rc - 'resource counter', tracks the number of resource properties with the same name. When the resource count reaches 0, any triggers specified using an on_zero attribute may be executed (see below). If Name is a tuple, the last element of the name can contain a wildcard, using the symbol '\\_'. This will make the resource counter keep track of any resources where all elements match except the last position. For example, {rc,l,{a,b,'\\_'}} would keep track of both {r,l,{a,b,1}} and {r,l,{a,b,2}}.

On-zero triggers:

Msg = {gproc, resource_on_zero, Context, Name, Pid}

reg_or_locate/1

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

reg_or_locate/2

Try registering a unique name, or return existing registration.

reg_or_locate/3

Spawn a process with a registered name, or return existing registration.

This function checks whether a local name is registered; if not, it spawns a new process (with spawn(Fun)) and gives it the name. The pid and value of the resulting registration is returned.

reg_other/2

Equivalent to reg_other(Key, Pid, default(Key), []).

reg_other/3

Equivalent to reg_other(Key, Pid, Value, []).

reg_other/4

Register name or property to another process.

Equivalent to reg/3, but allows for registration of another process instead of the current process.

Note that registering other processes introduces the possibility of confusing race conditions in user code. Letting each process register its own resources is highly recommended.

Only the following resource types can be registered through this function:

reg_shared/1

Register a resource, but don't tie it to a particular process.

reg_shared/2

Register a resource, but don't tie it to a particular process.

Shared resources are all unique. They remain until explicitly unregistered (using unreg_shared/1). The types of shared resources currently supported are counter and aggregated counter. In listings and query results, shared resources appear as other similar resources, except that Pid == shared. To wit, update_counter({c,l,myCounter}, shared, 1) would increment the shared counter myCounter with 1, provided it exists.

reg_shared/3

register_name/2

Behaviour support callback

reset_counter/1

Reads and resets a counter in a "thread-safe" way

This function reads the current value of a counter and then resets it to its initial value. The reset operation is done using update_counter/2, which allows for concurrent calls to update_counter/2 without losing updates. Aggregated counters are updated accordingly.

select/1

Perform a select operation on the process registry

When Arg = Contination, resume a gproc:select/1 operation (see ets:select/1

When Arg = sel_pattern(), this function executes a select operation, emulating ets:select/1

select/2 offers the opportunity to narrow the search (by limiting to only global or local scope, or a single type of object). When only a pattern as single argument is given, both global and local scope, as well as all types of object can be searched. Note that the pattern may still limit the select operation so that scanning the entire table is avoided.

select/2

Perform a select operation with limited context on the process registry

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

select/3

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

select_count/1

Equivalent to select_count(all, Pat).

select_count/2

Perform a select_count operation on the process registry.

send/2

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_attributes/2

Add/modify {Key, Value} attributes associated with a registration.

Gproc registration objects can have {Key, Value} attributes associated with them. These are stored in a way that doesn't affect the cost of name lookup.

set_attributes_shared/2

Add/modify {Key, Value} attributes associated with a shared registration.

Gproc registration objects can have {Key, Value} attributes associated with them. These are stored in a way that doesn't affect the cost of name lookup.

set_env/5

Updates the cached value as well as underlying environment.

This function should be exercised with caution, as it affects the larger environment outside gproc. This function modifies the cached value, and then proceeds to update the underlying environment (OS environment variable or application environment variable).

set_value/2

Sets the value of the registration given by Key

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

set_value_shared/2

Sets the value of the shared registration given by Key

Key is assumed to exist as a shared entity. If it doesn't, this function will exit.

start_link/0

Starts the gproc server.

table/0

Equivalent to table({all, all}).

table/1

Equivalent to table(Context, []).

table/2

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

Unregister a name or property.

unreg_other/2

Unregister a name registered to another process.

unreg_shared/1

Unregister a shared resource.

unregister_name/1

Equivalent to unreg / 1.

update_counter/2

Updates the counter registered as Key for the current process.

This function works almost exactly 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 or a unique name (update_counter/2 can be performed on names as well, but they do not count as counter objects, and do not affect aggregated counters).

Aggregated counters with the same name will be updated automatically. The UpdateOp patterns are the same as for ets:update_counter/3, except that the position is omitted; in gproc, the value position is always 3.

update_counter/3

update_counters/2

Update a list of counters

This function is not atomic, except (in a sense) for global counters. For local counters, it is more of a convenience function. For global counters, it is much more efficient than calling gproc:update_counter/2 for each individual counter.

update_shared_counter/2

Updates the shared counter registered as Key.

This function works almost exactly 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

Returns the pid registered as Key

whereis_name/1

Equivalent to where / 1.

wide_await/3

Wait for a local name to be registered on any of Nodes. This function works rather like await/2, but queries all nodes in the Nodes list at the same time. The first node to respond with a process registered as Key will provide the result. Other results are ignored. Key must be a unique name with local scope, i.e. {n,l,Name}.

Overview

Generated by EDoc