Extended process registry\nThis module implements an extended process registry.\nBehaviours: gen_server
.
Authors: Ulf Wiger (ulf@wiger.net
).\n
For a detailed description, see\nerlang07-wiger.pdf.
\n\nGproc relies on a central server and an ordered-set ets table.\nEffort is made to perform as much work as possible in the client without\nsacrificing consistency. A few things can be tuned by setting the following\napplication environment variables in the top application of gproc
\n(usually gproc
):
- \n
{ets_options, list()}
- Currently, the options{write_concurrency, F}
\nand{read_concurrency, F}
are allowed. The default is\n[{write_concurrency, true}, {read_concurrency, true}]
\n{server_options, list()}
- These will be passed as spawn options when\nstarting thegproc
andgproc_dist
servers. Default is[]
. It is\nlikely that{priority, high | max}
and/or increasingmin_heap_size
\nwill improve performance. \n
{'all','all'} is the default
\n\n\nctr_incr() = integer()\n
\nctr_setval() = integer()\n
\nctr_thr() = integer()\n
\nctr_update() = ctr_incr() | {ctr_incr(), ctr_thr(), ctr_setval()}\n
\nincrement() = ctr_incr() | ctr_update() | [ctr_update()]\n
update_counter increment
\n\n\nkeypat() = {sel_type() | sel_var(), l | g | sel_var(), any()}\n
\nmonitor_type() = info | standby | follow\n
\npidpat() = pid() | sel_var()\n
\nscope() = l | g\n
l = local registration; g = global registration
\n\n\nsel_pattern() = [{headpat(), Guards, Prod}]\n
\nsel_scope() = scope | all | global | local\n
\nsel_type() = type() | names | props | counters | aggr_counters\n
\nsel_var() = DollarVar | '_'\n
\ntype() = n | p | c | a\n
n = name; p = property; c = counter;\na = aggregate_counter
\n\n\nunique_id() = {n | a, scope(), any()}\n
add_global_aggr_counter/1 | Registers a global (unique) aggregated counter. |
add_global_counter/2 | Registers a global (non-unique) counter. |
add_global_name/1 | Registers a global (unique) name. |
add_global_property/2 | Registers a global (non-unique) property. |
add_local_aggr_counter/1 | Registers a local (unique) aggregated counter. |
add_local_counter/2 | Registers a local (non-unique) counter. |
add_local_name/1 | Registers a local (unique) name. |
add_local_property/2 | Registers a local (non-unique) property. |
add_shared_local_counter/2 | Registers a local shared (unique) counter. |
audit_process/1 | |
await/1 | Equivalent to await(Key, infinity). |
await/2 | Wait for a local name to be registered. |
await/3 | Wait for a local name to be registered on Node . |
bcast/2 | Equivalent to bcast(nodes(), Key, Msg). |
bcast/3 | Sends a message to processes corresponding to Key on Nodes. |
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\nThis function is the reverse of monitor/1. |
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 | 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. |
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. |
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 . |
goodbye/0 | Unregister all items of the calling process and inform gproc\nto forget about the calling process. |
i/0 | Similar to the built-in shell command i() but inserts information\nabout 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 | Lookup a global (unique) aggregated counter and returns its value. |
lookup_global_counters/1 | Look up all global (non-unique) instances of a given Counter. |
lookup_global_name/1 | Lookup a global unique name. |
lookup_global_properties/1 | Look up all global (non-unique) instances of a given Property. |
lookup_local_aggr_counter/1 | Lookup a local (unique) aggregated counter and returns its value. |
lookup_local_counters/1 | Look up all local (non-unique) instances of a given Counter. |
lookup_local_name/1 | Lookup a local unique name. |
lookup_local_properties/1 | Look up all local (non-unique) instances of a given Property. |
lookup_pid/1 | Lookup the Pid stored with a key. |
lookup_pids/1 | Returns a list of pids with the published key Key. |
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\nmonitor(Key, info) works much like erlang:monitor(process, Pid), but monitors\na unique name registered via gproc. |
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 local name to be registered. |
nb_wait/2 | Wait for a local name to be registered on Node . |
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_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. |
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. |
register_name/2 | Behaviour support callback. |
reset_counter/1 | Reads and resets a counter in a \"thread-safe\" way. |
select/1 | Perform a select operation on the process registry. |
select/2 | Perform a select operation with limited context on the process registry. |
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. |
set_attributes/2 | Add/modify {Key, Value} attributes associated with a registration. |
set_attributes_shared/2 | Add/modify {Key, Value} attributes associated with a shared registration. |
set_env/5 | Updates the cached value as well as underlying environment. |
set_value/2 | Sets the value of the registration given by Key. |
set_value_shared/2 | Sets the value of the shared registration given by Key. |
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. |
unreg/1 | Unregister a name or property. |
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. |
update_counter/3 | |
update_counters/2 | Update a list of counters. |
update_shared_counter/2 | Updates the shared counter registered as Key. |
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 . |
add_global_aggr_counter(Name) -> any()
Equivalent to reg({a, g, Name})
.
Registers a global (unique) aggregated counter.\n
\n\nadd_global_counter(Name, Initial) -> any()
Registers a global (non-unique) counter. @equiv reg({c,g,Name},Value)\n
\n\nadd_global_name(Name) -> any()
Registers a global (unique) name. @equiv reg({n,g,Name})\n
\n\nadd_global_property(Name, Value) -> any()
Registers a global (non-unique) property. @equiv reg({p,g,Name},Value)\n
\n\nadd_local_aggr_counter(Name) -> any()
Equivalent to reg({a, l, Name})
.
Registers a local (unique) aggregated counter.\n
\n\nadd_local_counter(Name, Initial) -> any()
Registers a local (non-unique) counter. @equiv reg({c,l,Name},Value)\n
\n\nadd_local_name(Name) -> any()
Registers a local (unique) name. @equiv reg({n,l,Name})\n
\n\nadd_local_property(Name, Value) -> any()
Registers a local (non-unique) property. @equiv reg({p,l,Name},Value)\n
\n\nadd_shared_local_counter(Name, Initial) -> any()
Equivalent to reg_shared({c, l, Name}, Value)
.
Registers a local shared (unique) counter.\n
\n\n\naudit_process(Pid::pid()) -> ok\n
\nawait(Key::key()) -> {pid(), Value}\n
Equivalent to await(Key, infinity)
.\n
\nawait(Key::key(), Timeout) -> {pid(), Value}\n
Timeout = integer() | infinity
Wait for a local name to be registered.\nThe function raises an exception if the timeout expires. Timeout must be\neither an interger > 0 or 'infinity'.\nA small optimization: we first perform a lookup, to see if the name\nis already registered. This way, the cost of the operation will be\nroughly the same as of where/1 in the case where the name is already\nregistered (the difference: await/2 also returns the value).\n
\n\n\nawait(Node::node(), Key::key(), Timeout) -> {pid(), Value}\n
Timeout = integer() | infinity
Wait for a local name to be registered on Node
.\nThis function works exactly like await/2
, but queries a remote\nnode instead. An exception is thrown if Node
cannot be reached. If gproc\nis not running on a given node, this is treated the same as the node being\ndown.\n
\nbcast(Key::key(), Msg::any()) -> Msg\n
Equivalent to bcast(nodes(), Key, Msg)
.\n
\nbcast(Nodes::[atom()], Key::key(), Msg::any()) -> Msg\n
Sends a message to processes corresponding to Key on Nodes.
\nThis function complements send/2
and works on locally registered resources\nthat send/2
supports. Messages are routed via a special broadcast server\non each node to ensure that ordering is preserved. Distributed delivery\nis asynchronous and carries the same guarantees as normal message passing\n(with the added proviso that the broadcast server also needs to be available).
See also: send/2.\n
\n\n\ncancel_wait(Key::key(), Ref) -> ok\n
Ref = all | reference()
Cancels a previous call to nb_wait/1
\nIf Ref = all
, all wait requests on Key
from the calling process\nare canceled.\n
\ncancel_wait(Node::node(), Key::key(), Ref) -> ok\n
Ref = all | reference()
Cancels a previous call to nb_wait/2
\nThis function works just like cancel_wait/2
, but talks to a remote\nnode.\n
cancel_wait_or_monitor(Key) -> any()
default(X1) -> any()
\ndemonitor(Key::key(), Ref::reference()) -> ok\n
Remove a monitor on a registered name\nThis function is the reverse of monitor/1. It removes a monitor previously\nset on a unique name. This function always succeeds given legal input.\n
\n\n\nBehaves as ets:first(Tab) for a given type of registration.
\nSee http://www.erlang.org/doc/man/ets.html#first-1
.\nThe registry behaves as an ordered_set table.\n
\nget_attribute(Key, Attribute::atom()) -> Value\n
Get attribute value of Attr
associated with Key
for most likely Pid.
The most likely Pid in this case is self()
for properties and counters,\nand the current registration holder in case of names or aggregated counters.\nAn exception is raised if Key
is not registered for the given process.\n
\nget_attribute(Key, Pid::pid() | shared, Attr::atom()) -> Value\n
Get the attribute value of Attr
associated with Key
for process Pid.
If Pid == shared
, the attribute of a shared key (see reg_shared/1
)\nwill be read.\n
\nget_attribute_shared(Key, Attr::atom()) -> Value\n
Get the attribute value of Attr
associated with the shared Key
.
Equivalent to get_attribute(Key, shared, Attr)
\n(see get_attribute/3
).\n
\nget_attributes(Key::key()) -> [{K, V}]\n
Equivalent to get_attributes(Key, self())
.
Get attributes associated with registration.\n
\n\n\nget_attributes(Key::key(), Pid::pid() | shared) -> [{K, V}]\n
Returns the list of attributes associated with the registration.
\nThis function raises a badarg
exception if there is no corresponding\nregistration.
\nget_env(Scope::scope(), App::atom(), Key::atom()) -> term()\n
Equivalent to get_env(Scope, App, Key, [app_env])
.\n
\nget_env(Scope::scope(), App::atom(), Key::atom(), Strategy) -> term()\n
Strategy = [Alternative]
Alternative = app_env | os_env | inherit | {inherit, pid()} | {inherit, unique_id()} | init_arg | {mnesia, ActivityType, Oid, Pos} | {default, term()} | error
Read an environment value, potentially cached as a gproc_env
property.
This function first tries to read the value of a cached property,\n{p, Scope, {gproc_env, App, Key}}
. If this fails, it will try the provided\nalternative strategy. Strategy
is a list of alternatives, tried in order.\nEach alternative can be one of:
- \n
app_env
- tryapplication:get_env(App, Key)
\nos_env
- tryos:getenv(ENV)
, whereENV
isKey
converted into an\nuppercase string \n{os_env, ENV}
- tryos:getenv(ENV)
\ninherit
- inherit the cached value, if any, held by the parent process. \n{inherit, Pid}
- inherit the cached value, if any, held byPid
. \n{inherit, Id}
- inherit the cached value, if any, held by the process\nregistered ingproc
asId
. \ninit_arg
- tryinit:get_argument(Key)
; expects a single value, if any. \n{mnesia, ActivityType, Oid, Pos}
- try\nmnesia:activity(ActivityType, fun() -> mnesia:read(Oid) end)
; retrieve\nthe value in positionPos
if object found. \n{default, Value}
- set a default value to return once alternatives have\nbeen exhausted; if not set,undefined
will be returned. \nerror
- raise an exception,erlang:error(gproc_env, [App, Key, Scope])
. \n
While any alternative can occur more than once, the only one that might make\nsense to use multiple times is {default, Value}
.
The return value will be one of:
\n- \n
- The value of the first matching alternative, or
error
eception,\nwhichever comes first \n - The last instance of
{default, Value}
, orundefined
, if there is no\nmatching alternative, default orerror
entry in the list. \n
The error
option can be used to assert that a value has been previously\ncached. Alternatively, it can be used to assert that a value is either cached\nor at least defined somewhere,\ne.g. get_env(l, mnesia, dir, [app_env, error])
.\n
\nget_set_env(Scope::scope(), App::atom(), Key::atom()) -> term()\n
Equivalent to get_set_env(Scope, App, Key, [app_env])
.\n
\nget_set_env(Scope::scope(), App::atom(), Key::atom(), Strategy) -> Value\n
Fetch and cache an environment value, if not already cached.
\nThis function does the same thing as get_env/4
, but also updates the\ncache. Note that the cache will be updated even if the result of the lookup\nis undefined
.
See also: get_env/4.\n
\n\n\nget_value(Key) -> Value\n
Reads the value stored with a key registered to the current process.
\nIf no such key is registered to the current process, this function exits.\n
\n\n\nget_value(Key, Pid) -> Value\n
Reads the value stored with a key registered to the process Pid.
\nIf Pid == shared
, the value of a shared key (see reg_shared/1
)\nwill be read.\n
\nget_value_shared(Key) -> Value\n
Reads the value stored with a shared key.
\nIf no such shared key is registered, this function exits.\n
\n\n\nAtomically transfers the key From
to the process identified by To
.
This function transfers any gproc key (name, property, counter, aggr counter)\nfrom one process to another, and returns the pid of the new owner.
\nTo
must be either a pid or a unique name (name or aggregated counter), but\ndoes not necessarily have to resolve to an existing process. If there is\nno process registered with the To
key, give_away/2
returns undefined
,\nand the From
key is effectively unregistered.
It is allowed to give away a key to oneself, but of course, this operation\nwill have no effect.
\nFails with badarg
if the calling process does not have a From
key\nregistered.\n
\ngoodbye() -> ok\n
Unregister all items of the calling process and inform gproc\nto forget about the calling process.
\nThis function is more efficient than letting gproc perform these\ncleanup operations.\n
\n\n\ni() -> ok\n
Similar to the built-in shell command i()
but inserts information\nabout names and properties registered in Gproc, where applicable.\n
\ninfo(Pid::pid()) -> ProcessInfo\n
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\naddition of a gproc
information item, containing the {Key,Value}
\npairs registered to the process.\n
\ninfo(Pid::pid(), Item::atom()) -> {Item, Info}\n
Similar to process_info(Pid, Item), but with additional gproc info.
\nFor Item = gproc
, this function returns a list of {Key, Value}
pairs\nregistered to the process Pid. For other values of Item, it returns the\nsame as http://www.erlang.org/doc/man/erlang.html#process_info-2
.\n
Behaves as ets:last(Tab) for a given type of registration.
\nSee http://www.erlang.org/doc/man/ets.html#last-1
.\nThe registry behaves as an ordered_set table.\n
\nlookup_global_aggr_counter(Name::any()) -> integer()\n
Equivalent to lookup_value({a, g, Name})
.
Lookup a global (unique) aggregated counter and returns its value.\nFails if there is no such object.\n
\n\n\nlookup_global_counters(Counter::any()) -> [{pid(), Value::integer()}]\n
Equivalent to lookup_values({c, g, Counter})
.
Look up all global (non-unique) instances of a given Counter.\nReturns a list of {Pid, Value} tuples for all matching objects.\n
\n\n\nlookup_global_name(Name::any()) -> pid()\n
Equivalent to where({n, g, Name})
.
Lookup a global unique name. Fails if there is no such name.\n
\n\n\nlookup_global_properties(Property::any()) -> [{pid(), Value}]\n
Equivalent to lookup_values({p, g, Property})
.
Look up all global (non-unique) instances of a given Property.\nReturns a list of {Pid, Value} tuples for all matching objects.\n
\n\n\nlookup_local_aggr_counter(Name::any()) -> integer()\n
Equivalent to where({a, l, Name})
.
Lookup a local (unique) aggregated counter and returns its value.\nFails if there is no such object.\n
\n\n\nlookup_local_counters(Counter::any()) -> [{pid(), Value::integer()}]\n
Equivalent to lookup_values({c, l, Counter})
.
Look up all local (non-unique) instances of a given Counter.\nReturns a list of {Pid, Value} tuples for all matching objects.\n
\n\n\nlookup_local_name(Name::any()) -> pid()\n
Equivalent to where({n, l, Name})
.
Lookup a local unique name. Fails if there is no such name.\n
\n\n\nlookup_local_properties(Property::any()) -> [{pid(), Value}]\n
Equivalent to lookup_values({p, l, Property})
.
Look up all local (non-unique) instances of a given Property.\nReturns a list of {Pid, Value} tuples for all matching objects.\n
\n\n\nlookup_pid(Key) -> Pid\n
Lookup the Pid stored with a key.
\n\n\n\nlookup_pids(Key::key()) -> [pid()]\n
Returns a list of pids with the published key Key
\nIf the type of registration is either name or aggregated counter,\nthis function will return either an empty list, or a list of one pid.\nFor non-unique types, the return value can be a list of any length.
\nNote: shared resources are not associated with any pid, and will\ntherefore be excluded.\n
\n\n\nlookup_value(Key) -> Value\n
Lookup the value stored with a key.
\n\n\n\nlookup_values(Key::key()) -> [{pid(), Value}]\n
Retrieve the {Pid,Value}
pairs corresponding to Key.
Key refer to any type of registry object. If it refers to a unique\nobject, the list will be of length 0 or 1. If it refers to a non-unique\nobject, the return value can be a list of any length.\n
\n\nmonitor(Key) -> any()
Equivalent to monitor(Key, info)
.\n
\nmonitor(Key::key(), Type::monitor_type()) -> reference()\n
monitor a registered name\nmonitor(Key, info)
works much like erlang:monitor(process, Pid), but monitors\na unique name registered via gproc. A message, {gproc, unreg, Ref, Key}
\nwill be sent to the requesting process, if the name is unregistered or\nthe registered process dies. If there is a standby monitor (see below), a\nmessage {gproc, {failover, ToPid}, Ref, Key}
is sent to all monitors.\nIf the name is passed to another process using give_away/2
, the event\n{gproc, {migrated, ToPid}, Ref, Key}
is sent to all monitors.
monitor(Key, standby)
sets up the monitoring process as a standby for the\nregistered name. If the registered process dies, the first standby process\ninherits the name, and a message {gproc, {failover, ToPid}, Ref, Key}
is\nsent to all monitors, including the one that inherited the name.
If the name is not yet registered, the unreg event is sent immediately.\nIf the calling process in this case tried to start a standby
monitoring,\nit receives the registered name and the failover event immediately.
monitor(Key, follow)
keeps monitoring the registered name even if it is\ntemporarily unregistered. The messages received are the same as for the other\nmonitor types, but {gproc, registered, Ref, Key}
is also sent when a new\nprocess registers the name.\n
Register multiple {Key,Value} pairs of a given type and scope.
\nThis function is more efficient than calling reg/2
repeatedly.\nIt is also atomic in regard to unique names; either all names are registered\nor none are.\n
Unregister multiple Key items of a given type and scope.
\nThis function is usually more efficient than calling unreg/1
\nrepeatedly.\n
\nnb_wait(Key::key()) -> Ref\n
Wait for a local name to be registered.\nThe caller can expect to receive a message,\n{gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.\n
\n\n\nnb_wait(Node::node(), Key::key()) -> Ref\n
Wait for a local name to be registered on Node
.\nThe caller can expect to receive a message,\n{gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.\n
Behaves as ets:next(Tab,Key) for a given type of registration.
\nSee http://www.erlang.org/doc/man/ets.html#next-2
.\nThe registry behaves as an ordered_set table.\n
Behaves as ets:prev(Tab,Key) for a given type of registration.
\nSee http://www.erlang.org/doc/man/ets.html#prev-2
.\nThe registry behaves as an ordered_set table.\n
\nreg(Key::key()) -> true\n
Equivalent to reg(Key, default(Key))
.\n
\nreg(Key::key(), Value) -> true\n
Register a name or property for the current process
\n\n\n\nreg_or_locate(Key::key()) -> true\n
Equivalent to reg_or_locate(Key, default(Key))
.\n
\nreg_or_locate(Key::key(), Value) -> {pid(), NewValue}\n
Try registering a unique name, or return existing registration.
\nThis function tries to register the name Key
, if available.\nIf such a registration object already exists, the pid and value of\nthe current registration is returned instead.\n
\nreg_or_locate(Key::key(), Value, Fun::function()) -> {pid(), NewValue}\n
Spawn a process with a registered name, or return existing registration.
\nThis function checks whether a local name is registered; if not, it spawns\na new process (with spawn(Fun)
) and gives it the name.\nThe pid and value of the resulting registration is returned.
When a global name is registered in this fashion, the process is\nspawned on the caller's node, and the group_leader of the spawned\nprocess is set to the group_leader of the calling process.\n
\n\n\nreg_shared(Key::key()) -> true\n
Register a resource, but don't tie it to a particular process.
\nreg_shared({c,l,C}) -> reg_shared({c,l,C}, 0).
\nreg_shared({a,l,A}) -> reg_shared({a,l,A}, undefined).
\n
\nreg_shared(Key::key(), Value) -> true\n
Register a resource, but don't tie it to a particular process.
\nShared resources are all unique. They remain until explicitly unregistered\n(using unreg_shared/1
). The types of shared resources currently\nsupported are counter
and aggregated counter
. In listings and query\nresults, shared resources appear as other similar resources, except that\nPid == shared
. To wit, update_counter({c,l,myCounter}, shared, 1) would\nincrement the shared counter myCounter
with 1, provided it exists.
A shared aggregated counter will track updates in exactly the same way as\nan aggregated counter which is owned by a process.\n
\n\n\nregister_name(Name::key(), Pid::pid()) -> yes | no\n
\nreset_counter(Key) -> {ValueBefore, ValueAfter}\n
Key = {c, Scope, Name}
Scope = l | g
ValueBefore = integer()
ValueAfter = integer()
Reads and resets a counter in a \"thread-safe\" way
\nThis function reads the current value of a counter and then resets it to its\ninitial value. The reset operation is done using update_counter/2
,\nwhich allows for concurrent calls to update_counter/2
without losing\nupdates. Aggregated counters are updated accordingly.\n
\nselect(Continuation::Arg) -> [Match] | {[Match], Continuation} | '$end_of_table'\n
Arg = Continuation | sel_pattern()
Match = {Key, Pid, Value}
Perform a select operation on the process registry
\nWhen Arg = Contination, resume a gproc:select/1 operation\n(see ets:select/1
\nWhen Arg = sel_pattern()
, this function executes a select operation,\nemulating ets:select/1
select/2
offers the opportunity to narrow the search\n(by limiting to only global or local scope, or a single type of object).\nWhen only a pattern as single argument is given, both global and local scope,\nas well as all types of object can be searched. Note that the pattern may\nstill limit the select operation so that scanning the entire table is avoided.
The physical representation in the registry may differ from the above,\nbut the select patterns are transformed appropriately. The logical\nrepresentation for the gproc select operations is given by\nheadpat()
.\n
\nselect(Context::context(), Pat::sel_pattern()) -> [{Key, Pid, Value}]\n
Perform a select operation with limited context on the process registry
\nThe physical representation in the registry may differ from the above,\nbut the select patterns are transformed appropriately.
\nNote that limiting the context is just a convenience function, allowing you\nto write a simpler select pattern and still avoid searching the entire\nregistry. Whenever variables are used in the head pattern, this will result\nin a wider scan, even if the values are restricted through a guard (e.g.\nselect([{'$1','$2','$3'}, [{'==', {element,1,'$1'}, p}], ...])
\nwill count as a wild pattern on the key and result in a full scan).\nIn this case, specifying a Context will allow gproc to perform some\nvariable substitution and ensure that the scan is limited.\n
\nselect(Context::context(), Pat::sel_patten(), Limit::integer()) -> {[Match], Continuation} | '$end_of_table'\n
Like select/2
but returns Limit objects at a time.
See http://www.erlang.org/doc/man/ets.html#select-3
.\n
\nselect_count(Pat::sel_pattern()) -> [sel_object()]\n
Equivalent to select_count(all, Pat)
.\n
\nselect_count(Context::context(), Pat::sel_pattern()) -> [{Key, Pid, Value}]\n
Perform a select_count operation on the process registry.
\nThe physical representation in the registry may differ from the above,\nbut the select patterns are transformed appropriately.\n
\n\n\nSends a message to the process, or processes, corresponding to Key.
\nIf Key belongs to a unique object (name or aggregated counter), this\nfunction will send a message to the corresponding process, or fail if there\nis no such process. If Key is for a non-unique object type (counter or\nproperty), Msg will be send to all processes that have such an object.
\nKey can also be anything that the erlang:send/2, or '!' operator accepts as a process\nidentifier, namely a pid(), an atom(), or {Name::atom(), Node::atom()}
.\n
\nset_attributes(Key::key(), Props::[{atom(), any()}]) -> true\n
Add/modify {Key, Value}
attributes associated with a registration.
Gproc registration objects can have {Key, Value}
attributes associated with\nthem. These are stored in a way that doesn't affect the cost of name lookup.
Attributs can be retrieved using gproc:get_attribute/3
or\ngproc:get_attributes/2
.\n
\nset_attributes_shared(Key::key(), Props::[{K, V}]) -> true\n
Add/modify {Key, Value}
attributes associated with a shared registration.
Gproc registration objects can have {Key, Value}
attributes associated with\nthem. These are stored in a way that doesn't affect the cost of name lookup.
Attributes can be retrieved using gproc:get_attribute/3
or\ngproc:get_attributes/2
.\n
\nset_env(Scope::scope(), App::atom(), Key::atom(), Value::term(), Strategy) -> Value\n
Strategy = [Alternative]
Alternative = app_env | os_env | {os_env, VAR} | {mnesia, ActivityType, Oid, Pos}
Updates the cached value as well as underlying environment.
\nThis function should be exercised with caution, as it affects the larger\nenvironment outside gproc. This function modifies the cached value, and then\nproceeds to update the underlying environment (OS environment variable or\napplication environment variable).
\nWhen the mnesia
alternative is used, gproc will try to update any existing\nobject, changing only the Pos
position. If no such object exists, it will\ncreate a new object, setting any other attributes (except Pos
and the key)\nto undefined
.\n
\nset_value(Key::key(), Value) -> true\n
Sets the value of the registration given by Key
\nKey is assumed to exist and belong to the calling process.\nIf it doesn't, this function will exit.
\nValue can be any term, unless the object is a counter, in which case\nit must be an integer.\n
\n\n\nset_value_shared(Key::key(), Value) -> true\n
Sets the value of the shared registration given by Key
\nKey is assumed to exist as a shared entity.\nIf it doesn't, this function will exit.
\nValue can be any term, unless the object is a counter, in which case\nit must be an integer.\n
\n\n\nstart_link() -> {ok, pid()}\n
Starts the gproc server.
\nThis function is intended to be called from gproc_sup, as part of\nstarting the gproc application.\n
\n\n\ntable() -> any()\n
Equivalent to table({all, all})
.\n
\ntable(Context::context()) -> any()\n
Equivalent to table(Context, [])
.\n
\ntable(Context::context(), Opts) -> any()\n
QLC table generator for the gproc registry.\nContext specifies which subset of the registry should be queried.\nSee http://www.erlang.org/doc/man/qlc.html
.
NOTE: By default, the gproc table generator will not filter out entries\nbelonging to processes that have just died, but which have yet to be cleared\nout of the registry. Use the option check_pids
(or {check_pids, true}
)\nif you want to filter out dead entries already in the query. There will be\nsome overhead associated with doing so, and given that the process monitoring\nis asynchronous, there can never be any guarantee that there are no dead\nentries in the list by the time your program processes it.
\nunreg(Key::key()) -> true\n
Unregister a name or property.\n
\n\n\nunreg_shared(Key::key()) -> true\n
Unregister a shared resource.\n
\n\nunregister_name(Key) -> any()
\nupdate_counter(Key::key(), Incr::increment()) -> integer()\n
Updates the counter registered as Key for the current process.
\nThis function works almost exactly like ets:update_counter/3\n(see http://www.erlang.org/doc/man/ets.html#update_counter-3
), but\nwill fail if the type of object referred to by Key is not a counter or\na unique name (update_counter/2 can be performed on names as well, but they\ndo not count as counter objects, and do not affect aggregated counters).
Aggregated counters with the same name will be updated automatically.\nThe UpdateOp
patterns are the same as for ets:update_counter/3
, except\nthat the position is omitted; in gproc, the value position is always 3
.
If Key
refers to a unique name, the operation will depend on the value\npart of the registration being an integer(). While non-integer values are\nnot permitted at all for counter objects, it is the user's responsibility to\nensure that a name, on which update_counter/2
is to be performed, has the\nappropriate value type.\n
update_counter(Key, Pid, Incr) -> any()
\nupdate_counters(X1::scope(), Cs::[{key(), pid(), increment()}]) -> [{key(), pid(), integer()}]\n
Update a list of counters
\nThis function is not atomic, except (in a sense) for global counters. For local counters,\nit is more of a convenience function. For global counters, it is much more efficient\nthan calling gproc:update_counter/2
for each individual counter.
The return value is the corresponding list of [{Counter, Pid, NewValue}]
.\n
\nupdate_shared_counter(Key::key(), Incr) -> integer() | [integer()]\n
Incr = IncrVal | UpdateOp | [UpdateOp]
UpdateOp = IncrVal | {IncrVal, Threshold, SetValue}
IncrVal = integer()
Updates the shared counter registered as Key.
\nThis function works almost exactly like ets:update_counter/3\n(see http://www.erlang.org/doc/man/ets.html#update_counter-3
), but\nwill fail if the type of object referred to by Key is not a counter.
Aggregated counters with the same name will be updated automatically.\nThe UpdateOp
patterns are the same as for ets:update_counter/3
, except\nthat the position is omitted; in gproc, the value position is always 3
.\n
\nwhere(Key::key()) -> pid()\n
Returns the pid registered as Key
\nThe type of registration must be either name or aggregated counter.\nOtherwise this function will exit. Use lookup_pids/1
in these\ncases.\n
whereis_name(Key) -> any()
\nwide_await(Nodes::[node()], Key::key(), Timeout) -> {pid(), Value}\n
Timeout = integer() | infinity
Wait for a local name to be registered on any of Nodes
.\nThis function works rather like await/2
, but queries all nodes in\nthe Nodes
list at the same time. The first node to respond with a\nprocess registered as Key
will provide the result. Other results are\nignored. Key
must be a unique name with local scope, i.e. {n,l,Name}
.
An exception is thrown upon timeout, or if no node can be reached (if gproc is\nnot running on a given node, this is treated the same as the node being down).
\n