|
|
@@ -1,6 +1,6 @@
|
|
|
|
|
|
|
|
|
-#Module gproc#
|
|
|
+# Module gproc #
|
|
|
* [Description](#description)
|
|
|
* [Data Types](#types)
|
|
|
* [Function Index](#index)
|
|
|
@@ -9,13 +9,12 @@
|
|
|
|
|
|
Extended process registry
|
|
|
This module implements an extended process registry.
|
|
|
-
|
|
|
__Behaviours:__ [`gen_server`](gen_server.md).
|
|
|
|
|
|
-__Authors:__ Ulf Wiger ([`ulf@wiger.net`](mailto:ulf@wiger.net)).<a name="description"></a>
|
|
|
-
|
|
|
-##Description##
|
|
|
+__Authors:__ Ulf Wiger ([`ulf@wiger.net`](mailto:ulf@wiger.net)).
|
|
|
+<a name="description"></a>
|
|
|
|
|
|
+## Description ##
|
|
|
|
|
|
|
|
|
|
|
|
@@ -24,8 +23,8 @@ For a detailed description, see
|
|
|
|
|
|
|
|
|
|
|
|
-##Tuning Gproc performance##
|
|
|
|
|
|
+## Tuning Gproc performance ##
|
|
|
|
|
|
|
|
|
|
|
|
@@ -35,6 +34,7 @@ sacrificing consistency. A few things can be tuned by setting the following
|
|
|
application environment variables in the top application of `gproc`
|
|
|
(usually `gproc`):
|
|
|
|
|
|
+
|
|
|
* `{ets_options, list()}` - Currently, the options `{write_concurrency, F}`
|
|
|
and `{read_concurrency, F}` are allowed. The default is
|
|
|
`[{write_concurrency, true}, {read_concurrency, true}]`
|
|
|
@@ -45,274 +45,357 @@ will improve performance.
|
|
|
|
|
|
<a name="types"></a>
|
|
|
|
|
|
-##Data Types##
|
|
|
+## Data Types ##
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-context">context()</a>##
|
|
|
+### <a name="type-context">context()</a> ###
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>context() = {<a href="#type-scope">scope()</a>, <a href="#type-type">type()</a>} | <a href="#type-type">type()</a></pre>
|
|
|
+<pre><code>
|
|
|
+context() = {<a href="#type-scope">scope()</a>, <a href="#type-type">type()</a>} | <a href="#type-type">type()</a>
|
|
|
+</code></pre>
|
|
|
+
|
|
|
|
|
|
|
|
|
{'all','all'} is the default
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-ctr_incr">ctr_incr()</a>##
|
|
|
+
|
|
|
+### <a name="type-ctr_incr">ctr_incr()</a> ###
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+ctr_incr() = integer()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+### <a name="type-ctr_setval">ctr_setval()</a> ###
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+ctr_setval() = integer()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>ctr_incr() = integer()</pre>
|
|
|
|
|
|
+### <a name="type-ctr_thr">ctr_thr()</a> ###
|
|
|
|
|
|
|
|
|
-###<a name="type-ctr_setval">ctr_setval()</a>##
|
|
|
|
|
|
+<pre><code>
|
|
|
+ctr_thr() = integer()
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
-<pre>ctr_setval() = integer()</pre>
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-ctr_thr">ctr_thr()</a>##
|
|
|
+### <a name="type-ctr_update">ctr_update()</a> ###
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>ctr_thr() = integer()</pre>
|
|
|
+<pre><code>
|
|
|
+ctr_update() = <a href="#type-ctr_incr">ctr_incr()</a> | {<a href="#type-ctr_incr">ctr_incr()</a>, <a href="#type-ctr_thr">ctr_thr()</a>, <a href="#type-ctr_setval">ctr_setval()</a>}
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-ctr_update">ctr_update()</a>##
|
|
|
|
|
|
|
|
|
+### <a name="type-headpat">headpat()</a> ###
|
|
|
|
|
|
-<pre>ctr_update() = <a href="#type-ctr_incr">ctr_incr()</a> | {<a href="#type-ctr_incr">ctr_incr()</a>, <a href="#type-ctr_thr">ctr_thr()</a>, <a href="#type-ctr_setval">ctr_setval()</a>}</pre>
|
|
|
|
|
|
|
|
|
+<pre><code>
|
|
|
+headpat() = {<a href="#type-keypat">keypat()</a>, <a href="#type-pidpat">pidpat()</a>, ValPat}
|
|
|
+</code></pre>
|
|
|
|
|
|
-###<a name="type-headpat">headpat()</a>##
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>headpat() = {<a href="#type-keypat">keypat()</a>, <a href="#type-pidpat">pidpat()</a>, ValPat}</pre>
|
|
|
|
|
|
+### <a name="type-increment">increment()</a> ###
|
|
|
|
|
|
|
|
|
-###<a name="type-increment">increment()</a>##
|
|
|
|
|
|
+<pre><code>
|
|
|
+increment() = <a href="#type-ctr_incr">ctr_incr()</a> | <a href="#type-ctr_update">ctr_update()</a> | [<a href="#type-ctr_update">ctr_update()</a>]
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
-<pre>increment() = <a href="#type-ctr_incr">ctr_incr()</a> | <a href="#type-ctr_update">ctr_update()</a> | [<a href="#type-ctr_update">ctr_update()</a>]</pre>
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-key">key()</a>##
|
|
|
+### <a name="type-key">key()</a> ###
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>key() = {<a href="#type-type">type()</a>, <a href="#type-scope">scope()</a>, any()}</pre>
|
|
|
+<pre><code>
|
|
|
+key() = {<a href="#type-type">type()</a>, <a href="#type-scope">scope()</a>, any()}
|
|
|
+</code></pre>
|
|
|
+
|
|
|
|
|
|
|
|
|
update_counter increment
|
|
|
|
|
|
|
|
|
-###<a name="type-keypat">keypat()</a>##
|
|
|
|
|
|
+### <a name="type-keypat">keypat()</a> ###
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+keypat() = {<a href="#type-sel_type">sel_type()</a> | <a href="#type-sel_var">sel_var()</a>, l | g | <a href="#type-sel_var">sel_var()</a>, any()}
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+### <a name="type-pidpat">pidpat()</a> ###
|
|
|
|
|
|
|
|
|
-<pre>keypat() = {<a href="#type-sel_type">sel_type()</a> | <a href="#type-sel_var">sel_var()</a>, l | g | <a href="#type-sel_var">sel_var()</a>, any()}</pre>
|
|
|
|
|
|
+<pre><code>
|
|
|
+pidpat() = pid() | <a href="#type-sel_var">sel_var()</a>
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
-###<a name="type-pidpat">pidpat()</a>##
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>pidpat() = pid() | <a href="#type-sel_var">sel_var()</a></pre>
|
|
|
+### <a name="type-reg_id">reg_id()</a> ###
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-reg_id">reg_id()</a>##
|
|
|
+<pre><code>
|
|
|
+reg_id() = {<a href="#type-type">type()</a>, <a href="#type-scope">scope()</a>, any()}
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>reg_id() = {<a href="#type-type">type()</a>, <a href="#type-scope">scope()</a>, any()}</pre>
|
|
|
|
|
|
|
|
|
+### <a name="type-scope">scope()</a> ###
|
|
|
|
|
|
-###<a name="type-scope">scope()</a>##
|
|
|
|
|
|
|
|
|
+<pre><code>
|
|
|
+scope() = l | g
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>scope() = l | g</pre>
|
|
|
|
|
|
|
|
|
l = local registration; g = global registration
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-sel_pattern">sel_pattern()</a>##
|
|
|
|
|
|
+### <a name="type-sel_pattern">sel_pattern()</a> ###
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+sel_pattern() = [{<a href="#type-headpat">headpat()</a>, Guards, Prod}]
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+### <a name="type-sel_scope">sel_scope()</a> ###
|
|
|
|
|
|
|
|
|
-<pre>sel_pattern() = [{<a href="#type-headpat">headpat()</a>, Guards, Prod}]</pre>
|
|
|
|
|
|
+<pre><code>
|
|
|
+sel_scope() = scope | all | global | local
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
-###<a name="type-sel_scope">sel_scope()</a>##
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>sel_scope() = scope | all | global | local</pre>
|
|
|
+### <a name="type-sel_type">sel_type()</a> ###
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-sel_type">sel_type()</a>##
|
|
|
+<pre><code>
|
|
|
+sel_type() = <a href="#type-type">type()</a> | names | props | counters | aggr_counters
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
|
|
|
-<pre>sel_type() = <a href="#type-type">type()</a> | names | props | counters | aggr_counters</pre>
|
|
|
|
|
|
|
|
|
+### <a name="type-sel_var">sel_var()</a> ###
|
|
|
|
|
|
-###<a name="type-sel_var">sel_var()</a>##
|
|
|
|
|
|
|
|
|
+<pre><code>
|
|
|
+sel_var() = DollarVar | '_'
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>sel_var() = DollarVar | '_'</pre>
|
|
|
|
|
|
|
|
|
|
|
|
-###<a name="type-type">type()</a>##
|
|
|
|
|
|
+### <a name="type-type">type()</a> ###
|
|
|
|
|
|
|
|
|
-<pre>type() = n | p | c | a</pre>
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+type() = n | p | c | a
|
|
|
+</code></pre>
|
|
|
+
|
|
|
|
|
|
|
|
|
n = name; p = property; c = counter;
|
|
|
a = aggregate_counter
|
|
|
|
|
|
|
|
|
-###<a name="type-unique_id">unique_id()</a>##
|
|
|
|
|
|
+### <a name="type-unique_id">unique_id()</a> ###
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+unique_id() = {n | a, <a href="#type-scope">scope()</a>, any()}
|
|
|
+</code></pre>
|
|
|
|
|
|
|
|
|
-<pre>unique_id() = {n | a, <a href="#type-scope">scope()</a>, any()}</pre>
|
|
|
<a name="index"></a>
|
|
|
|
|
|
-##Function Index##
|
|
|
+## Function Index ##
|
|
|
|
|
|
|
|
|
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_global_aggr_counter-1">add_global_aggr_counter/1</a></td><td>Registers a global (unique) aggregated counter.</td></tr><tr><td valign="top"><a href="#add_global_counter-2">add_global_counter/2</a></td><td>Registers a global (non-unique) counter.</td></tr><tr><td valign="top"><a href="#add_global_name-1">add_global_name/1</a></td><td>Registers a global (unique) name.</td></tr><tr><td valign="top"><a href="#add_global_property-2">add_global_property/2</a></td><td>Registers a global (non-unique) property.</td></tr><tr><td valign="top"><a href="#add_local_aggr_counter-1">add_local_aggr_counter/1</a></td><td>Registers a local (unique) aggregated counter.</td></tr><tr><td valign="top"><a href="#add_local_counter-2">add_local_counter/2</a></td><td>Registers a local (non-unique) counter.</td></tr><tr><td valign="top"><a href="#add_local_name-1">add_local_name/1</a></td><td>Registers a local (unique) name.</td></tr><tr><td valign="top"><a href="#add_local_property-2">add_local_property/2</a></td><td>Registers a local (non-unique) property.</td></tr><tr><td valign="top"><a href="#add_shared_local_counter-2">add_shared_local_counter/2</a></td><td>Registers a local shared (unique) counter.</td></tr><tr><td valign="top"><a href="#audit_process-1">audit_process/1</a></td><td></td></tr><tr><td valign="top"><a href="#await-1">await/1</a></td><td>Equivalent to <a href="#await-2"><tt>await(Key, infinity)</tt></a>.</td></tr><tr><td valign="top"><a href="#await-2">await/2</a></td><td>Wait for a local name to be registered.</td></tr><tr><td valign="top"><a href="#await-3">await/3</a></td><td>Wait for a local name to be registered on <code>Node</code>.</td></tr><tr><td valign="top"><a href="#bcast-2">bcast/2</a></td><td>Equivalent to <a href="#bcast-3"><tt>bcast(nodes(), Key, Msg)</tt></a>.</td></tr><tr><td valign="top"><a href="#bcast-3">bcast/3</a></td><td>Sends a message to processes corresponding to Key on Nodes.</td></tr><tr><td valign="top"><a href="#cancel_wait-2">cancel_wait/2</a></td><td>Cancels a previous call to nb_wait/1.</td></tr><tr><td valign="top"><a href="#cancel_wait-3">cancel_wait/3</a></td><td>Cancels a previous call to nb_wait/2.</td></tr><tr><td valign="top"><a href="#cancel_wait_or_monitor-1">cancel_wait_or_monitor/1</a></td><td></td></tr><tr><td valign="top"><a href="#default-1">default/1</a></td><td></td></tr><tr><td valign="top"><a href="#demonitor-2">demonitor/2</a></td><td>Remove a monitor on a registered name
|
|
|
-This function is the reverse of monitor/1.</td></tr><tr><td valign="top"><a href="#first-1">first/1</a></td><td>Behaves as ets:first(Tab) for a given type of registration object.</td></tr><tr><td valign="top"><a href="#get_env-3">get_env/3</a></td><td>Equivalent to <a href="#get_env-4"><tt>get_env(Scope, App, Key, [app_env])</tt></a>.</td></tr><tr><td valign="top"><a href="#get_env-4">get_env/4</a></td><td>Read an environment value, potentially cached as a <code>gproc_env</code> property.</td></tr><tr><td valign="top"><a href="#get_set_env-3">get_set_env/3</a></td><td>Equivalent to <a href="#get_set_env-4"><tt>get_set_env(Scope, App, Key, [app_env])</tt></a>.</td></tr><tr><td valign="top"><a href="#get_set_env-4">get_set_env/4</a></td><td>Fetch and cache an environment value, if not already cached.</td></tr><tr><td valign="top"><a href="#get_value-1">get_value/1</a></td><td>Reads the value stored with a key registered to the current process.</td></tr><tr><td valign="top"><a href="#get_value-2">get_value/2</a></td><td>Reads the value stored with a key registered to the process Pid.</td></tr><tr><td valign="top"><a href="#give_away-2">give_away/2</a></td><td>Atomically transfers the key <code>From</code> to the process identified by <code>To</code>.</td></tr><tr><td valign="top"><a href="#goodbye-0">goodbye/0</a></td><td>Unregister all items of the calling process and inform gproc
|
|
|
+This function is the reverse of monitor/1.</td></tr><tr><td valign="top"><a href="#first-1">first/1</a></td><td>Behaves as ets:first(Tab) for a given type of registration.</td></tr><tr><td valign="top"><a href="#get_attribute-2">get_attribute/2</a></td><td>Get attribute value of <code>Attr</code> associated with <code>Key</code> for most likely Pid.</td></tr><tr><td valign="top"><a href="#get_attribute-3">get_attribute/3</a></td><td>Get the attribute value of <code>Attr</code> associated with <code>Key</code> for process Pid.</td></tr><tr><td valign="top"><a href="#get_attributes-1">get_attributes/1</a></td><td>Get attributes associated with registration.</td></tr><tr><td valign="top"><a href="#get_attributes-2">get_attributes/2</a></td><td>Returns the list of attributes associated with the registration.</td></tr><tr><td valign="top"><a href="#get_env-3">get_env/3</a></td><td>Equivalent to <a href="#get_env-4"><tt>get_env(Scope, App, Key, [app_env])</tt></a>.</td></tr><tr><td valign="top"><a href="#get_env-4">get_env/4</a></td><td>Read an environment value, potentially cached as a <code>gproc_env</code> property.</td></tr><tr><td valign="top"><a href="#get_set_env-3">get_set_env/3</a></td><td>Equivalent to <a href="#get_set_env-4"><tt>get_set_env(Scope, App, Key, [app_env])</tt></a>.</td></tr><tr><td valign="top"><a href="#get_set_env-4">get_set_env/4</a></td><td>Fetch and cache an environment value, if not already cached.</td></tr><tr><td valign="top"><a href="#get_value-1">get_value/1</a></td><td>Reads the value stored with a key registered to the current process.</td></tr><tr><td valign="top"><a href="#get_value-2">get_value/2</a></td><td>Reads the value stored with a key registered to the process Pid.</td></tr><tr><td valign="top"><a href="#give_away-2">give_away/2</a></td><td>Atomically transfers the key <code>From</code> to the process identified by <code>To</code>.</td></tr><tr><td valign="top"><a href="#goodbye-0">goodbye/0</a></td><td>Unregister all items of the calling process and inform gproc
|
|
|
to forget about the calling process.</td></tr><tr><td valign="top"><a href="#i-0">i/0</a></td><td>Similar to the built-in shell command <code>i()</code> but inserts information
|
|
|
-about names and properties registered in Gproc, where applicable.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Similar to <code>process_info(Pid)</code> but with additional gproc info.</td></tr><tr><td valign="top"><a href="#info-2">info/2</a></td><td>Similar to process_info(Pid, Item), but with additional gproc info.</td></tr><tr><td valign="top"><a href="#last-1">last/1</a></td><td>Behaves as ets:last(Tab) for a given type of registration object.</td></tr><tr><td valign="top"><a href="#lookup_global_aggr_counter-1">lookup_global_aggr_counter/1</a></td><td>Lookup a global (unique) aggregated counter and returns its value.</td></tr><tr><td valign="top"><a href="#lookup_global_counters-1">lookup_global_counters/1</a></td><td>Look up all global (non-unique) instances of a given Counter.</td></tr><tr><td valign="top"><a href="#lookup_global_name-1">lookup_global_name/1</a></td><td>Lookup a global unique name.</td></tr><tr><td valign="top"><a href="#lookup_global_properties-1">lookup_global_properties/1</a></td><td>Look up all global (non-unique) instances of a given Property.</td></tr><tr><td valign="top"><a href="#lookup_local_aggr_counter-1">lookup_local_aggr_counter/1</a></td><td>Lookup a local (unique) aggregated counter and returns its value.</td></tr><tr><td valign="top"><a href="#lookup_local_counters-1">lookup_local_counters/1</a></td><td>Look up all local (non-unique) instances of a given Counter.</td></tr><tr><td valign="top"><a href="#lookup_local_name-1">lookup_local_name/1</a></td><td>Lookup a local unique name.</td></tr><tr><td valign="top"><a href="#lookup_local_properties-1">lookup_local_properties/1</a></td><td>Look up all local (non-unique) instances of a given Property.</td></tr><tr><td valign="top"><a href="#lookup_pid-1">lookup_pid/1</a></td><td>Lookup the Pid stored with a key.</td></tr><tr><td valign="top"><a href="#lookup_pids-1">lookup_pids/1</a></td><td>Returns a list of pids with the published key Key.</td></tr><tr><td valign="top"><a href="#lookup_value-1">lookup_value/1</a></td><td>Lookup the value stored with a key.</td></tr><tr><td valign="top"><a href="#lookup_values-1">lookup_values/1</a></td><td>Retrieve the <code>{Pid,Value}</code> pairs corresponding to Key.</td></tr><tr><td valign="top"><a href="#monitor-1">monitor/1</a></td><td>monitor a registered name
|
|
|
+about names and properties registered in Gproc, where applicable.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Similar to <code>process_info(Pid)</code> but with additional gproc info.</td></tr><tr><td valign="top"><a href="#info-2">info/2</a></td><td>Similar to process_info(Pid, Item), but with additional gproc info.</td></tr><tr><td valign="top"><a href="#last-1">last/1</a></td><td>Behaves as ets:last(Tab) for a given type of registration.</td></tr><tr><td valign="top"><a href="#lookup_global_aggr_counter-1">lookup_global_aggr_counter/1</a></td><td>Lookup a global (unique) aggregated counter and returns its value.</td></tr><tr><td valign="top"><a href="#lookup_global_counters-1">lookup_global_counters/1</a></td><td>Look up all global (non-unique) instances of a given Counter.</td></tr><tr><td valign="top"><a href="#lookup_global_name-1">lookup_global_name/1</a></td><td>Lookup a global unique name.</td></tr><tr><td valign="top"><a href="#lookup_global_properties-1">lookup_global_properties/1</a></td><td>Look up all global (non-unique) instances of a given Property.</td></tr><tr><td valign="top"><a href="#lookup_local_aggr_counter-1">lookup_local_aggr_counter/1</a></td><td>Lookup a local (unique) aggregated counter and returns its value.</td></tr><tr><td valign="top"><a href="#lookup_local_counters-1">lookup_local_counters/1</a></td><td>Look up all local (non-unique) instances of a given Counter.</td></tr><tr><td valign="top"><a href="#lookup_local_name-1">lookup_local_name/1</a></td><td>Lookup a local unique name.</td></tr><tr><td valign="top"><a href="#lookup_local_properties-1">lookup_local_properties/1</a></td><td>Look up all local (non-unique) instances of a given Property.</td></tr><tr><td valign="top"><a href="#lookup_pid-1">lookup_pid/1</a></td><td>Lookup the Pid stored with a key.</td></tr><tr><td valign="top"><a href="#lookup_pids-1">lookup_pids/1</a></td><td>Returns a list of pids with the published key Key.</td></tr><tr><td valign="top"><a href="#lookup_value-1">lookup_value/1</a></td><td>Lookup the value stored with a key.</td></tr><tr><td valign="top"><a href="#lookup_values-1">lookup_values/1</a></td><td>Retrieve the <code>{Pid,Value}</code> pairs corresponding to Key.</td></tr><tr><td valign="top"><a href="#monitor-1">monitor/1</a></td><td>monitor a registered name
|
|
|
This function works much like erlang:monitor(process, Pid), but monitors
|
|
|
-a unique name registered via gproc.</td></tr><tr><td valign="top"><a href="#mreg-3">mreg/3</a></td><td>Register multiple {Key,Value} pairs of a given type and scope.</td></tr><tr><td valign="top"><a href="#munreg-3">munreg/3</a></td><td>Unregister multiple Key items of a given type and scope.</td></tr><tr><td valign="top"><a href="#nb_wait-1">nb_wait/1</a></td><td>Wait for a local name to be registered.</td></tr><tr><td valign="top"><a href="#nb_wait-2">nb_wait/2</a></td><td>Wait for a local name to be registered on <code>Node</code>.</td></tr><tr><td valign="top"><a href="#next-2">next/2</a></td><td>Behaves as ets:next(Tab,Key) for a given type of registration object.</td></tr><tr><td valign="top"><a href="#prev-2">prev/2</a></td><td>Behaves as ets:prev(Tab,Key) for a given type of registration object.</td></tr><tr><td valign="top"><a href="#reg-1">reg/1</a></td><td>Equivalent to <a href="#reg-2"><tt>reg(Key, default(Key))</tt></a>.</td></tr><tr><td valign="top"><a href="#reg-2">reg/2</a></td><td>Register a name or property for the current process.</td></tr><tr><td valign="top"><a href="#reg_or_locate-1">reg_or_locate/1</a></td><td>Equivalent to <a href="#reg_or_locate-2"><tt>reg_or_locate(Key, default(Key))</tt></a>.</td></tr><tr><td valign="top"><a href="#reg_or_locate-2">reg_or_locate/2</a></td><td>Try registering a unique name, or return existing registration.</td></tr><tr><td valign="top"><a href="#reg_or_locate-3">reg_or_locate/3</a></td><td>Spawn a process with a registered name, or return existing registration.</td></tr><tr><td valign="top"><a href="#reg_shared-1">reg_shared/1</a></td><td>Register a resource, but don't tie it to a particular process.</td></tr><tr><td valign="top"><a href="#reg_shared-2">reg_shared/2</a></td><td>Register a resource, but don't tie it to a particular process.</td></tr><tr><td valign="top"><a href="#register_name-2">register_name/2</a></td><td>Behaviour support callback.</td></tr><tr><td valign="top"><a href="#reset_counter-1">reset_counter/1</a></td><td>Reads and resets a counter in a "thread-safe" way.</td></tr><tr><td valign="top"><a href="#select-1">select/1</a></td><td>Perform a select operation on the process registry.</td></tr><tr><td valign="top"><a href="#select-2">select/2</a></td><td>Perform a select operation with limited context on the process registry.</td></tr><tr><td valign="top"><a href="#select-3">select/3</a></td><td>Like <a href="#select-2"><code>select/2</code></a> but returns Limit objects at a time.</td></tr><tr><td valign="top"><a href="#select_count-1">select_count/1</a></td><td>Equivalent to <a href="#select_count-2"><tt>select_count(all, Pat)</tt></a>.</td></tr><tr><td valign="top"><a href="#select_count-2">select_count/2</a></td><td>Perform a select_count operation on the process registry.</td></tr><tr><td valign="top"><a href="#send-2">send/2</a></td><td>Sends a message to the process, or processes, corresponding to Key.</td></tr><tr><td valign="top"><a href="#set_env-5">set_env/5</a></td><td>Updates the cached value as well as underlying environment.</td></tr><tr><td valign="top"><a href="#set_value-2">set_value/2</a></td><td>Sets the value of the registeration entry given by Key.</td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td>Starts the gproc server.</td></tr><tr><td valign="top"><a href="#table-0">table/0</a></td><td>Equivalent to <a href="#table-1"><tt>table({all, all})</tt></a>.</td></tr><tr><td valign="top"><a href="#table-1">table/1</a></td><td>Equivalent to <a href="#table-2"><tt>table(Context, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#table-2">table/2</a></td><td>QLC table generator for the gproc registry.</td></tr><tr><td valign="top"><a href="#unreg-1">unreg/1</a></td><td>Unregister a name or property.</td></tr><tr><td valign="top"><a href="#unreg_shared-1">unreg_shared/1</a></td><td>Unregister a shared resource.</td></tr><tr><td valign="top"><a href="#unregister_name-1">unregister_name/1</a></td><td>Equivalent to <tt>unreg / 1</tt>.</td></tr><tr><td valign="top"><a href="#update_counter-2">update_counter/2</a></td><td>Updates the counter registered as Key for the current process.</td></tr><tr><td valign="top"><a href="#update_counters-2">update_counters/2</a></td><td>Update a list of counters.</td></tr><tr><td valign="top"><a href="#update_shared_counter-2">update_shared_counter/2</a></td><td>Updates the shared counter registered as Key.</td></tr><tr><td valign="top"><a href="#where-1">where/1</a></td><td>Returns the pid registered as Key.</td></tr><tr><td valign="top"><a href="#whereis_name-1">whereis_name/1</a></td><td>Equivalent to <tt>where / 1</tt>.</td></tr><tr><td valign="top"><a href="#wide_await-3">wide_await/3</a></td><td>Wait for a local name to be registered on any of <code>Nodes</code>.</td></tr></table>
|
|
|
+a unique name registered via gproc.</td></tr><tr><td valign="top"><a href="#mreg-3">mreg/3</a></td><td>Register multiple {Key,Value} pairs of a given type and scope.</td></tr><tr><td valign="top"><a href="#munreg-3">munreg/3</a></td><td>Unregister multiple Key items of a given type and scope.</td></tr><tr><td valign="top"><a href="#nb_wait-1">nb_wait/1</a></td><td>Wait for a local name to be registered.</td></tr><tr><td valign="top"><a href="#nb_wait-2">nb_wait/2</a></td><td>Wait for a local name to be registered on <code>Node</code>.</td></tr><tr><td valign="top"><a href="#next-2">next/2</a></td><td>Behaves as ets:next(Tab,Key) for a given type of registration.</td></tr><tr><td valign="top"><a href="#prev-2">prev/2</a></td><td>Behaves as ets:prev(Tab,Key) for a given type of registration.</td></tr><tr><td valign="top"><a href="#reg-1">reg/1</a></td><td>Equivalent to <a href="#reg-2"><tt>reg(Key, default(Key))</tt></a>.</td></tr><tr><td valign="top"><a href="#reg-2">reg/2</a></td><td>Register a name or property for the current process.</td></tr><tr><td valign="top"><a href="#reg_or_locate-1">reg_or_locate/1</a></td><td>Equivalent to <a href="#reg_or_locate-2"><tt>reg_or_locate(Key, default(Key))</tt></a>.</td></tr><tr><td valign="top"><a href="#reg_or_locate-2">reg_or_locate/2</a></td><td>Try registering a unique name, or return existing registration.</td></tr><tr><td valign="top"><a href="#reg_or_locate-3">reg_or_locate/3</a></td><td>Spawn a process with a registered name, or return existing registration.</td></tr><tr><td valign="top"><a href="#reg_shared-1">reg_shared/1</a></td><td>Register a resource, but don't tie it to a particular process.</td></tr><tr><td valign="top"><a href="#reg_shared-2">reg_shared/2</a></td><td>Register a resource, but don't tie it to a particular process.</td></tr><tr><td valign="top"><a href="#register_name-2">register_name/2</a></td><td>Behaviour support callback.</td></tr><tr><td valign="top"><a href="#reset_counter-1">reset_counter/1</a></td><td>Reads and resets a counter in a "thread-safe" way.</td></tr><tr><td valign="top"><a href="#select-1">select/1</a></td><td>Perform a select operation on the process registry.</td></tr><tr><td valign="top"><a href="#select-2">select/2</a></td><td>Perform a select operation with limited context on the process registry.</td></tr><tr><td valign="top"><a href="#select-3">select/3</a></td><td>Like <a href="#select-2"><code>select/2</code></a> but returns Limit objects at a time.</td></tr><tr><td valign="top"><a href="#select_count-1">select_count/1</a></td><td>Equivalent to <a href="#select_count-2"><tt>select_count(all, Pat)</tt></a>.</td></tr><tr><td valign="top"><a href="#select_count-2">select_count/2</a></td><td>Perform a select_count operation on the process registry.</td></tr><tr><td valign="top"><a href="#send-2">send/2</a></td><td>Sends a message to the process, or processes, corresponding to Key.</td></tr><tr><td valign="top"><a href="#set_attributes-2">set_attributes/2</a></td><td>Add/modify <code>{Key, Value}</code> attributes associated with a registration.</td></tr><tr><td valign="top"><a href="#set_attributes_shared-2">set_attributes_shared/2</a></td><td>Add/modify <code>{Key, Value}</code> attributes associated with a shared registration.</td></tr><tr><td valign="top"><a href="#set_env-5">set_env/5</a></td><td>Updates the cached value as well as underlying environment.</td></tr><tr><td valign="top"><a href="#set_value-2">set_value/2</a></td><td>Sets the value of the registration given by Key.</td></tr><tr><td valign="top"><a href="#set_value_shared-2">set_value_shared/2</a></td><td>Sets the value of the shared registration given by Key.</td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td>Starts the gproc server.</td></tr><tr><td valign="top"><a href="#table-0">table/0</a></td><td>Equivalent to <a href="#table-1"><tt>table({all, all})</tt></a>.</td></tr><tr><td valign="top"><a href="#table-1">table/1</a></td><td>Equivalent to <a href="#table-2"><tt>table(Context, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#table-2">table/2</a></td><td>QLC table generator for the gproc registry.</td></tr><tr><td valign="top"><a href="#unreg-1">unreg/1</a></td><td>Unregister a name or property.</td></tr><tr><td valign="top"><a href="#unreg_shared-1">unreg_shared/1</a></td><td>Unregister a shared resource.</td></tr><tr><td valign="top"><a href="#unregister_name-1">unregister_name/1</a></td><td>Equivalent to <tt>unreg / 1</tt>.</td></tr><tr><td valign="top"><a href="#update_counter-2">update_counter/2</a></td><td>Updates the counter registered as Key for the current process.</td></tr><tr><td valign="top"><a href="#update_counter-3">update_counter/3</a></td><td></td></tr><tr><td valign="top"><a href="#update_counters-2">update_counters/2</a></td><td>Update a list of counters.</td></tr><tr><td valign="top"><a href="#update_shared_counter-2">update_shared_counter/2</a></td><td>Updates the shared counter registered as Key.</td></tr><tr><td valign="top"><a href="#where-1">where/1</a></td><td>Returns the pid registered as Key.</td></tr><tr><td valign="top"><a href="#whereis_name-1">whereis_name/1</a></td><td>Equivalent to <tt>where / 1</tt>.</td></tr><tr><td valign="top"><a href="#wide_await-3">wide_await/3</a></td><td>Wait for a local name to be registered on any of <code>Nodes</code>.</td></tr></table>
|
|
|
|
|
|
|
|
|
<a name="functions"></a>
|
|
|
|
|
|
-##Function Details##
|
|
|
+## Function Details ##
|
|
|
|
|
|
<a name="add_global_aggr_counter-1"></a>
|
|
|
|
|
|
-###add_global_aggr_counter/1##
|
|
|
-
|
|
|
+### add_global_aggr_counter/1 ###
|
|
|
|
|
|
`add_global_aggr_counter(Name) -> any()`
|
|
|
|
|
|
Equivalent to [`reg({a, g, Name})`](#reg-1).
|
|
|
|
|
|
-Registers a global (unique) aggregated counter.<a name="add_global_counter-2"></a>
|
|
|
-
|
|
|
-###add_global_counter/2##
|
|
|
+Registers a global (unique) aggregated counter.
|
|
|
+<a name="add_global_counter-2"></a>
|
|
|
|
|
|
+### add_global_counter/2 ###
|
|
|
|
|
|
`add_global_counter(Name, Initial) -> any()`
|
|
|
|
|
|
-Registers a global (non-unique) counter. @equiv reg({c,g,Name},Value)<a name="add_global_name-1"></a>
|
|
|
-
|
|
|
-###add_global_name/1##
|
|
|
+Registers a global (non-unique) counter. @equiv reg({c,g,Name},Value)
|
|
|
+<a name="add_global_name-1"></a>
|
|
|
|
|
|
+### add_global_name/1 ###
|
|
|
|
|
|
`add_global_name(Name) -> any()`
|
|
|
|
|
|
-Registers a global (unique) name. @equiv reg({n,g,Name})<a name="add_global_property-2"></a>
|
|
|
-
|
|
|
-###add_global_property/2##
|
|
|
+Registers a global (unique) name. @equiv reg({n,g,Name})
|
|
|
+<a name="add_global_property-2"></a>
|
|
|
|
|
|
+### add_global_property/2 ###
|
|
|
|
|
|
`add_global_property(Name, Value) -> any()`
|
|
|
|
|
|
-Registers a global (non-unique) property. @equiv reg({p,g,Name},Value)<a name="add_local_aggr_counter-1"></a>
|
|
|
-
|
|
|
-###add_local_aggr_counter/1##
|
|
|
+Registers a global (non-unique) property. @equiv reg({p,g,Name},Value)
|
|
|
+<a name="add_local_aggr_counter-1"></a>
|
|
|
|
|
|
+### add_local_aggr_counter/1 ###
|
|
|
|
|
|
`add_local_aggr_counter(Name) -> any()`
|
|
|
|
|
|
Equivalent to [`reg({a, l, Name})`](#reg-1).
|
|
|
|
|
|
-Registers a local (unique) aggregated counter.<a name="add_local_counter-2"></a>
|
|
|
-
|
|
|
-###add_local_counter/2##
|
|
|
+Registers a local (unique) aggregated counter.
|
|
|
+<a name="add_local_counter-2"></a>
|
|
|
|
|
|
+### add_local_counter/2 ###
|
|
|
|
|
|
`add_local_counter(Name, Initial) -> any()`
|
|
|
|
|
|
-Registers a local (non-unique) counter. @equiv reg({c,l,Name},Value)<a name="add_local_name-1"></a>
|
|
|
-
|
|
|
-###add_local_name/1##
|
|
|
+Registers a local (non-unique) counter. @equiv reg({c,l,Name},Value)
|
|
|
+<a name="add_local_name-1"></a>
|
|
|
|
|
|
+### add_local_name/1 ###
|
|
|
|
|
|
`add_local_name(Name) -> any()`
|
|
|
|
|
|
-Registers a local (unique) name. @equiv reg({n,l,Name})<a name="add_local_property-2"></a>
|
|
|
-
|
|
|
-###add_local_property/2##
|
|
|
+Registers a local (unique) name. @equiv reg({n,l,Name})
|
|
|
+<a name="add_local_property-2"></a>
|
|
|
|
|
|
+### add_local_property/2 ###
|
|
|
|
|
|
`add_local_property(Name, Value) -> any()`
|
|
|
|
|
|
-Registers a local (non-unique) property. @equiv reg({p,l,Name},Value)<a name="add_shared_local_counter-2"></a>
|
|
|
-
|
|
|
-###add_shared_local_counter/2##
|
|
|
+Registers a local (non-unique) property. @equiv reg({p,l,Name},Value)
|
|
|
+<a name="add_shared_local_counter-2"></a>
|
|
|
|
|
|
+### add_shared_local_counter/2 ###
|
|
|
|
|
|
`add_shared_local_counter(Name, Initial) -> any()`
|
|
|
|
|
|
Equivalent to [`reg_shared({c, l, Name}, Value)`](#reg_shared-2).
|
|
|
|
|
|
-Registers a local shared (unique) counter.<a name="audit_process-1"></a>
|
|
|
+Registers a local shared (unique) counter.
|
|
|
+<a name="audit_process-1"></a>
|
|
|
+
|
|
|
+### audit_process/1 ###
|
|
|
|
|
|
-###audit_process/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+audit_process(Pid::pid()) -> ok
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>audit_process(Pid::pid()) -> ok</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
+
|
|
|
<a name="await-1"></a>
|
|
|
|
|
|
-###await/1##
|
|
|
+### await/1 ###
|
|
|
+
|
|
|
|
|
|
+<pre><code>
|
|
|
+await(Key::<a href="#type-key">key()</a>) -> {pid(), Value}
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>await(Key::<a href="#type-key">key()</a>) -> {pid(), Value}</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`await(Key, infinity)`](#await-2).<a name="await-2"></a>
|
|
|
+Equivalent to [`await(Key, infinity)`](#await-2).
|
|
|
+<a name="await-2"></a>
|
|
|
|
|
|
-###await/2##
|
|
|
+### await/2 ###
|
|
|
|
|
|
|
|
|
-<pre>await(Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}</pre>
|
|
|
-<ul class="definitions"><li><pre>Timeout = integer() | infinity</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+await(Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<ul class="definitions"><li><code>Timeout = integer() | infinity</code></li></ul>
|
|
|
|
|
|
Wait for a local name to be registered.
|
|
|
The function raises an exception if the timeout expires. Timeout must be
|
|
|
@@ -320,128 +403,234 @@ 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).<a name="await-3"></a>
|
|
|
+registered (the difference: await/2 also returns the value).
|
|
|
+<a name="await-3"></a>
|
|
|
+
|
|
|
+### await/3 ###
|
|
|
|
|
|
-###await/3##
|
|
|
|
|
|
+<pre><code>
|
|
|
+await(Node::node(), Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>await(Node::node(), Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}</pre>
|
|
|
-<ul class="definitions"><li><pre>Timeout = integer() | infinity</pre></li></ul>
|
|
|
+<ul class="definitions"><li><code>Timeout = integer() | infinity</code></li></ul>
|
|
|
|
|
|
Wait for a local name to be registered on `Node`.
|
|
|
This function works exactly like [`await/2`](#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.<a name="bcast-2"></a>
|
|
|
+down.
|
|
|
+<a name="bcast-2"></a>
|
|
|
+
|
|
|
+### bcast/2 ###
|
|
|
|
|
|
-###bcast/2##
|
|
|
|
|
|
+<pre><code>
|
|
|
+bcast(Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>bcast(Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`bcast(nodes(), Key, Msg)`](#bcast-3).<a name="bcast-3"></a>
|
|
|
+Equivalent to [`bcast(nodes(), Key, Msg)`](#bcast-3).
|
|
|
+<a name="bcast-3"></a>
|
|
|
|
|
|
-###bcast/3##
|
|
|
+### bcast/3 ###
|
|
|
|
|
|
|
|
|
-<pre>bcast(Nodes::[atom()], Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+bcast(Nodes::[atom()], Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Sends a message to processes corresponding to Key on Nodes.
|
|
|
|
|
|
+
|
|
|
This function complements `send/2` and works on locally registered resources
|
|
|
that `send/2` supports. Messages are routed via a special broadcast server
|
|
|
on each node to ensure that ordering is preserved. Distributed delivery
|
|
|
is asynchronous and carries the same guarantees as normal message passing
|
|
|
(with the added proviso that the broadcast server also needs to be available).
|
|
|
|
|
|
-__See also:__ [send/2](#send-2).<a name="cancel_wait-2"></a>
|
|
|
+__See also:__ [send/2](#send-2).
|
|
|
+<a name="cancel_wait-2"></a>
|
|
|
|
|
|
-###cancel_wait/2##
|
|
|
+### cancel_wait/2 ###
|
|
|
|
|
|
|
|
|
-<pre>cancel_wait(Key::<a href="#type-key">key()</a>, Ref) -> ok</pre>
|
|
|
-<ul class="definitions"><li><pre>Ref = all | reference()</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+cancel_wait(Key::<a href="#type-key">key()</a>, Ref) -> ok
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Ref = all | reference()</code></li></ul>
|
|
|
|
|
|
|
|
|
Cancels a previous call to nb_wait/1
|
|
|
|
|
|
+
|
|
|
If `Ref = all`, all wait requests on `Key` from the calling process
|
|
|
-are canceled.<a name="cancel_wait-3"></a>
|
|
|
+are canceled.
|
|
|
+<a name="cancel_wait-3"></a>
|
|
|
|
|
|
-###cancel_wait/3##
|
|
|
+### cancel_wait/3 ###
|
|
|
|
|
|
|
|
|
-<pre>cancel_wait(Node::node(), Key::<a href="#type-key">key()</a>, Ref) -> ok</pre>
|
|
|
-<ul class="definitions"><li><pre>Ref = all | reference()</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+cancel_wait(Node::node(), Key::<a href="#type-key">key()</a>, Ref) -> ok
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Ref = all | reference()</code></li></ul>
|
|
|
|
|
|
|
|
|
Cancels a previous call to nb_wait/2
|
|
|
|
|
|
-This function works just like [`cancel_wait/2`](#cancel_wait-2), but talks to a remote
|
|
|
-node.<a name="cancel_wait_or_monitor-1"></a>
|
|
|
|
|
|
-###cancel_wait_or_monitor/1##
|
|
|
+This function works just like [`cancel_wait/2`](#cancel_wait-2), but talks to a remote
|
|
|
+node.
|
|
|
+<a name="cancel_wait_or_monitor-1"></a>
|
|
|
|
|
|
+### cancel_wait_or_monitor/1 ###
|
|
|
|
|
|
`cancel_wait_or_monitor(Key) -> any()`
|
|
|
|
|
|
-<a name="default-1"></a>
|
|
|
|
|
|
-###default/1##
|
|
|
+<a name="default-1"></a>
|
|
|
|
|
|
+### default/1 ###
|
|
|
|
|
|
`default(X1) -> any()`
|
|
|
|
|
|
+
|
|
|
<a name="demonitor-2"></a>
|
|
|
|
|
|
-###demonitor/2##
|
|
|
+### demonitor/2 ###
|
|
|
+
|
|
|
|
|
|
+<pre><code>
|
|
|
+demonitor(Key::<a href="#type-key">key()</a>, Ref::reference()) -> ok
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>demonitor(Key::<a href="#type-key">key()</a>, Ref::reference()) -> ok</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
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.<a name="first-1"></a>
|
|
|
+set on a unique name. This function always succeeds given legal input.
|
|
|
+<a name="first-1"></a>
|
|
|
|
|
|
-###first/1##
|
|
|
+### first/1 ###
|
|
|
|
|
|
|
|
|
-<pre>first(Context::<a href="#type-context">context()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'</pre>
|
|
|
+<pre><code>
|
|
|
+first(Context::<a href="#type-context">context()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
+Behaves as ets:first(Tab) for a given type of registration.
|
|
|
|
|
|
-Behaves as ets:first(Tab) for a given type of registration object.
|
|
|
|
|
|
See [`http://www.erlang.org/doc/man/ets.html#first-1`](http://www.erlang.org/doc/man/ets.html#first-1).
|
|
|
-The registry behaves as an ordered_set table.<a name="get_env-3"></a>
|
|
|
+The registry behaves as an ordered_set table.
|
|
|
+<a name="get_attribute-2"></a>
|
|
|
+
|
|
|
+### get_attribute/2 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+get_attribute(Key, Attribute::atom()) -> Value
|
|
|
+</code></pre>
|
|
|
|
|
|
-###get_env/3##
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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,
|
|
|
+and the current registration holder in case of names or aggregated counters.
|
|
|
+An exception is raised if `Key` is not registered for the given process.
|
|
|
+<a name="get_attribute-3"></a>
|
|
|
+
|
|
|
+### get_attribute/3 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+get_attribute(Key, Pid::pid() | shared, Attr::atom()) -> Value
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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`](#reg_shared-1))
|
|
|
+will be read.
|
|
|
+<a name="get_attributes-1"></a>
|
|
|
+
|
|
|
+### get_attributes/1 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+get_attributes(Key::<a href="#type-key">key()</a>) -> [{K, V}]
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
+Equivalent to [`get_attributes(Key, self())`](#get_attributes-2).
|
|
|
+
|
|
|
+Get attributes associated with registration.
|
|
|
+<a name="get_attributes-2"></a>
|
|
|
+
|
|
|
+### get_attributes/2 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+get_attributes(Key::<a href="#type-key">key()</a>, Pid::pid() | shared) -> [{K, V}]
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+Returns the list of attributes associated with the registration.
|
|
|
+
|
|
|
+
|
|
|
+This function raises a `badarg` exception if there is no corresponding
|
|
|
+registration.
|
|
|
|
|
|
+<a name="get_env-3"></a>
|
|
|
+
|
|
|
+### get_env/3 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+get_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom()) -> term()
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>get_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom()) -> term()</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`get_env(Scope, App, Key, [app_env])`](#get_env-4).<a name="get_env-4"></a>
|
|
|
+Equivalent to [`get_env(Scope, App, Key, [app_env])`](#get_env-4).
|
|
|
+<a name="get_env-4"></a>
|
|
|
|
|
|
-###get_env/4##
|
|
|
+### get_env/4 ###
|
|
|
|
|
|
|
|
|
-<pre>get_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Strategy) -> term()</pre>
|
|
|
-<ul class="definitions"><li><pre>Strategy = [Alternative]</pre></li><li><pre>Alternative = app_env | os_env | inherit | {inherit, pid()} | {inherit, <a href="#type-unique_id">unique_id()</a>} | init_arg | {mnesia, ActivityType, Oid, Pos} | {default, term()} | error</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+get_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Strategy) -> term()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Strategy = [Alternative]</code></li><li><code>Alternative = app_env | os_env | inherit | {inherit, pid()} | {inherit, <a href="#type-unique_id">unique_id()</a>} | init_arg | {mnesia, ActivityType, Oid, Pos} | {default, term()} | error</code></li></ul>
|
|
|
|
|
|
|
|
|
Read an environment value, potentially cached as a `gproc_env` property.
|
|
|
@@ -487,71 +676,91 @@ whichever comes first
|
|
|
* The last instance of `{default, Value}`, or `undefined`, if there is no
|
|
|
matching alternative, default or `error` entry in the list.
|
|
|
|
|
|
+
|
|
|
The `error` option can be used to assert that a value has been previously
|
|
|
cached. Alternatively, it can be used to assert that a value is either cached
|
|
|
or at least defined somewhere,
|
|
|
-e.g. `get_env(l, mnesia, dir, [app_env, error])`.<a name="get_set_env-3"></a>
|
|
|
+e.g. `get_env(l, mnesia, dir, [app_env, error])`.
|
|
|
+<a name="get_set_env-3"></a>
|
|
|
+
|
|
|
+### get_set_env/3 ###
|
|
|
|
|
|
-###get_set_env/3##
|
|
|
|
|
|
+<pre><code>
|
|
|
+get_set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom()) -> term()
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>get_set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom()) -> term()</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`get_set_env(Scope, App, Key, [app_env])`](#get_set_env-4).<a name="get_set_env-4"></a>
|
|
|
+Equivalent to [`get_set_env(Scope, App, Key, [app_env])`](#get_set_env-4).
|
|
|
+<a name="get_set_env-4"></a>
|
|
|
|
|
|
-###get_set_env/4##
|
|
|
+### get_set_env/4 ###
|
|
|
|
|
|
|
|
|
-<pre>get_set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Strategy) -> Value</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+get_set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Strategy) -> Value
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Fetch and cache an environment value, if not already cached.
|
|
|
|
|
|
+
|
|
|
This function does the same thing as [`get_env/4`](#get_env-4), but also updates the
|
|
|
cache. Note that the cache will be updated even if the result of the lookup
|
|
|
is `undefined`.
|
|
|
|
|
|
|
|
|
-__See also:__ [get_env/4](#get_env-4).<a name="get_value-1"></a>
|
|
|
+__See also:__ [get_env/4](#get_env-4).
|
|
|
+<a name="get_value-1"></a>
|
|
|
|
|
|
-###get_value/1##
|
|
|
+### get_value/1 ###
|
|
|
|
|
|
|
|
|
-<pre>get_value(Key) -> Value</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+get_value(Key) -> Value
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Reads the value stored with a key registered to the current process.
|
|
|
|
|
|
-If no such key is registered to the current process, this function exits.<a name="get_value-2"></a>
|
|
|
|
|
|
-###get_value/2##
|
|
|
+If no such key is registered to the current process, this function exits.
|
|
|
+<a name="get_value-2"></a>
|
|
|
|
|
|
+### get_value/2 ###
|
|
|
|
|
|
-<pre>get_value(Key, Pid) -> Value</pre>
|
|
|
-<br></br>
|
|
|
|
|
|
+<pre><code>
|
|
|
+get_value(Key, Pid) -> Value
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Reads the value stored with a key registered to the process Pid.
|
|
|
|
|
|
+
|
|
|
If `Pid == shared`, the value of a shared key (see [`reg_shared/1`](#reg_shared-1))
|
|
|
-will be read.<a name="give_away-2"></a>
|
|
|
+will be read.
|
|
|
+<a name="give_away-2"></a>
|
|
|
|
|
|
-###give_away/2##
|
|
|
+### give_away/2 ###
|
|
|
|
|
|
|
|
|
-<pre>give_away(From::<a href="#type-key">key()</a>, To::pid() | <a href="#type-key">key()</a>) -> undefined | pid()</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+give_away(From::<a href="#type-key">key()</a>, To::pid() | <a href="#type-key">key()</a>) -> undefined | pid()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -574,227 +783,304 @@ 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.<a name="goodbye-0"></a>
|
|
|
+registered.
|
|
|
+<a name="goodbye-0"></a>
|
|
|
|
|
|
-###goodbye/0##
|
|
|
+### goodbye/0 ###
|
|
|
|
|
|
|
|
|
-<pre>goodbye() -> ok</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+goodbye() -> ok
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Unregister all items of the calling process and inform gproc
|
|
|
to forget about the calling process.
|
|
|
|
|
|
+
|
|
|
This function is more efficient than letting gproc perform these
|
|
|
-cleanup operations.<a name="i-0"></a>
|
|
|
+cleanup operations.
|
|
|
+<a name="i-0"></a>
|
|
|
|
|
|
-###i/0##
|
|
|
+### i/0 ###
|
|
|
|
|
|
|
|
|
-<pre>i() -> ok</pre>
|
|
|
+<pre><code>
|
|
|
+i() -> ok
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Similar to the built-in shell command `i()` but inserts information
|
|
|
-about names and properties registered in Gproc, where applicable.<a name="info-1"></a>
|
|
|
+about names and properties registered in Gproc, where applicable.
|
|
|
+<a name="info-1"></a>
|
|
|
|
|
|
-###info/1##
|
|
|
+### info/1 ###
|
|
|
|
|
|
|
|
|
-<pre>info(Pid::pid()) -> ProcessInfo</pre>
|
|
|
-<ul class="definitions"><li><pre>ProcessInfo = [{gproc, [{Key, Value}]} | ProcessInfo]</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+info(Pid::pid()) -> ProcessInfo
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>ProcessInfo = [{gproc, [{Key, Value}]} | ProcessInfo]</code></li></ul>
|
|
|
|
|
|
|
|
|
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.<a name="info-2"></a>
|
|
|
+pairs registered to the process.
|
|
|
+<a name="info-2"></a>
|
|
|
|
|
|
-###info/2##
|
|
|
+### info/2 ###
|
|
|
|
|
|
|
|
|
-<pre>info(Pid::pid(), Item::atom()) -> {Item, Info}</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+info(Pid::pid(), Item::atom()) -> {Item, Info}
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
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`](http://www.erlang.org/doc/man/erlang.html#process_info-2).<a name="last-1"></a>
|
|
|
+same as [`http://www.erlang.org/doc/man/erlang.html#process_info-2`](http://www.erlang.org/doc/man/erlang.html#process_info-2).
|
|
|
+<a name="last-1"></a>
|
|
|
+
|
|
|
+### last/1 ###
|
|
|
|
|
|
-###last/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+last(Context::<a href="#type-context">context()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>last(Context::<a href="#type-context">context()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
+Behaves as ets:last(Tab) for a given type of registration.
|
|
|
|
|
|
-Behaves as ets:last(Tab) for a given type of registration object.
|
|
|
|
|
|
See [`http://www.erlang.org/doc/man/ets.html#last-1`](http://www.erlang.org/doc/man/ets.html#last-1).
|
|
|
-The registry behaves as an ordered_set table.<a name="lookup_global_aggr_counter-1"></a>
|
|
|
+The registry behaves as an ordered_set table.
|
|
|
+<a name="lookup_global_aggr_counter-1"></a>
|
|
|
|
|
|
-###lookup_global_aggr_counter/1##
|
|
|
+### lookup_global_aggr_counter/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_global_aggr_counter(Name::any()) -> integer()</pre>
|
|
|
+<pre><code>
|
|
|
+lookup_global_aggr_counter(Name::any()) -> integer()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`where({a, g, Name})`](#where-1).
|
|
|
|
|
|
Lookup a global (unique) aggregated counter and returns its value.
|
|
|
-Fails if there is no such object.<a name="lookup_global_counters-1"></a>
|
|
|
+Fails if there is no such object.
|
|
|
+<a name="lookup_global_counters-1"></a>
|
|
|
+
|
|
|
+### lookup_global_counters/1 ###
|
|
|
|
|
|
-###lookup_global_counters/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+lookup_global_counters(Counter::any()) -> [{pid(), Value::integer()}]
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>lookup_global_counters(Counter::any()) -> [{pid(), Value::integer()}]</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`lookup_values({c, g, Counter})`](#lookup_values-1).
|
|
|
|
|
|
Look up all global (non-unique) instances of a given Counter.
|
|
|
-Returns a list of {Pid, Value} tuples for all matching objects.<a name="lookup_global_name-1"></a>
|
|
|
+Returns a list of {Pid, Value} tuples for all matching objects.
|
|
|
+<a name="lookup_global_name-1"></a>
|
|
|
|
|
|
-###lookup_global_name/1##
|
|
|
+### lookup_global_name/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_global_name(Name::any()) -> pid()</pre>
|
|
|
+<pre><code>
|
|
|
+lookup_global_name(Name::any()) -> pid()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`where({n, g, Name})`](#where-1).
|
|
|
|
|
|
-Lookup a global unique name. Fails if there is no such name.<a name="lookup_global_properties-1"></a>
|
|
|
+Lookup a global unique name. Fails if there is no such name.
|
|
|
+<a name="lookup_global_properties-1"></a>
|
|
|
+
|
|
|
+### lookup_global_properties/1 ###
|
|
|
|
|
|
-###lookup_global_properties/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+lookup_global_properties(Property::any()) -> [{pid(), Value}]
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>lookup_global_properties(Property::any()) -> [{pid(), Value}]</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`lookup_values({p, g, Property})`](#lookup_values-1).
|
|
|
|
|
|
Look up all global (non-unique) instances of a given Property.
|
|
|
-Returns a list of {Pid, Value} tuples for all matching objects.<a name="lookup_local_aggr_counter-1"></a>
|
|
|
+Returns a list of {Pid, Value} tuples for all matching objects.
|
|
|
+<a name="lookup_local_aggr_counter-1"></a>
|
|
|
|
|
|
-###lookup_local_aggr_counter/1##
|
|
|
+### lookup_local_aggr_counter/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_local_aggr_counter(Name::any()) -> integer()</pre>
|
|
|
+<pre><code>
|
|
|
+lookup_local_aggr_counter(Name::any()) -> integer()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`where({a, l, Name})`](#where-1).
|
|
|
|
|
|
Lookup a local (unique) aggregated counter and returns its value.
|
|
|
-Fails if there is no such object.<a name="lookup_local_counters-1"></a>
|
|
|
+Fails if there is no such object.
|
|
|
+<a name="lookup_local_counters-1"></a>
|
|
|
+
|
|
|
+### lookup_local_counters/1 ###
|
|
|
|
|
|
-###lookup_local_counters/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+lookup_local_counters(Counter::any()) -> [{pid(), Value::integer()}]
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>lookup_local_counters(Counter::any()) -> [{pid(), Value::integer()}]</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`lookup_values({c, l, Counter})`](#lookup_values-1).
|
|
|
|
|
|
Look up all local (non-unique) instances of a given Counter.
|
|
|
-Returns a list of {Pid, Value} tuples for all matching objects.<a name="lookup_local_name-1"></a>
|
|
|
+Returns a list of {Pid, Value} tuples for all matching objects.
|
|
|
+<a name="lookup_local_name-1"></a>
|
|
|
|
|
|
-###lookup_local_name/1##
|
|
|
+### lookup_local_name/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_local_name(Name::any()) -> pid()</pre>
|
|
|
+<pre><code>
|
|
|
+lookup_local_name(Name::any()) -> pid()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`where({n, l, Name})`](#where-1).
|
|
|
|
|
|
-Lookup a local unique name. Fails if there is no such name.<a name="lookup_local_properties-1"></a>
|
|
|
+Lookup a local unique name. Fails if there is no such name.
|
|
|
+<a name="lookup_local_properties-1"></a>
|
|
|
+
|
|
|
+### lookup_local_properties/1 ###
|
|
|
|
|
|
-###lookup_local_properties/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+lookup_local_properties(Property::any()) -> [{pid(), Value}]
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>lookup_local_properties(Property::any()) -> [{pid(), Value}]</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Equivalent to [`lookup_values({p, l, Property})`](#lookup_values-1).
|
|
|
|
|
|
Look up all local (non-unique) instances of a given Property.
|
|
|
-Returns a list of {Pid, Value} tuples for all matching objects.<a name="lookup_pid-1"></a>
|
|
|
+Returns a list of {Pid, Value} tuples for all matching objects.
|
|
|
+<a name="lookup_pid-1"></a>
|
|
|
|
|
|
-###lookup_pid/1##
|
|
|
+### lookup_pid/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_pid(Key) -> Pid</pre>
|
|
|
+<pre><code>
|
|
|
+lookup_pid(Key) -> Pid
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Lookup the Pid stored with a key.
|
|
|
+
|
|
|
<a name="lookup_pids-1"></a>
|
|
|
|
|
|
-###lookup_pids/1##
|
|
|
+### lookup_pids/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_pids(Key::<a href="#type-key">key()</a>) -> [pid()]</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+lookup_pids(Key::<a href="#type-key">key()</a>) -> [pid()]
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Returns a list of pids with the published key Key
|
|
|
|
|
|
-If the type of registration entry is either name or aggregated counter,
|
|
|
+
|
|
|
+
|
|
|
+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.<a name="lookup_value-1"></a>
|
|
|
+For non-unique types, the return value can be a list of any length.
|
|
|
+
|
|
|
+
|
|
|
+Note: shared resources are not associated with any pid, and will
|
|
|
+therefore be excluded.
|
|
|
+<a name="lookup_value-1"></a>
|
|
|
+
|
|
|
+### lookup_value/1 ###
|
|
|
|
|
|
-###lookup_value/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+lookup_value(Key) -> Value
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>lookup_value(Key) -> Value</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Lookup the value stored with a key.
|
|
|
+
|
|
|
<a name="lookup_values-1"></a>
|
|
|
|
|
|
-###lookup_values/1##
|
|
|
+### lookup_values/1 ###
|
|
|
|
|
|
|
|
|
-<pre>lookup_values(Key::<a href="#type-key">key()</a>) -> [{pid(), Value}]</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+lookup_values(Key::<a href="#type-key">key()</a>) -> [{pid(), Value}]
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
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.<a name="monitor-1"></a>
|
|
|
+object, the return value can be a list of any length.
|
|
|
+<a name="monitor-1"></a>
|
|
|
|
|
|
-###monitor/1##
|
|
|
+### monitor/1 ###
|
|
|
|
|
|
|
|
|
-<pre>monitor(Key::<a href="#type-key">key()</a>) -> reference()</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+monitor(Key::<a href="#type-key">key()</a>) -> reference()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -804,139 +1090,183 @@ 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 the name is not yet registered, the same message is sent immediately.<a name="mreg-3"></a>
|
|
|
|
|
|
-###mreg/3##
|
|
|
+If the name is not yet registered, the same message is sent immediately.
|
|
|
+<a name="mreg-3"></a>
|
|
|
|
|
|
+### mreg/3 ###
|
|
|
|
|
|
-<pre>mreg(T::<a href="#type-type">type()</a>, C::<a href="#type-scope">scope()</a>, KVL::[{Key::any(), Value::any()}]) -> true</pre>
|
|
|
-<br></br>
|
|
|
|
|
|
+<pre><code>
|
|
|
+mreg(T::<a href="#type-type">type()</a>, C::<a href="#type-scope">scope()</a>, KVL::[{Key::any(), Value::any()}]) -> true
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Register multiple {Key,Value} pairs of a given type and scope.
|
|
|
|
|
|
+
|
|
|
This function is more efficient than calling [`reg/2`](#reg-2) repeatedly.
|
|
|
It is also atomic in regard to unique names; either all names are registered
|
|
|
-or none are.<a name="munreg-3"></a>
|
|
|
+or none are.
|
|
|
+<a name="munreg-3"></a>
|
|
|
|
|
|
-###munreg/3##
|
|
|
+### munreg/3 ###
|
|
|
|
|
|
|
|
|
-<pre>munreg(T::<a href="#type-type">type()</a>, C::<a href="#type-scope">scope()</a>, L::[Key::any()]) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+munreg(T::<a href="#type-type">type()</a>, C::<a href="#type-scope">scope()</a>, L::[Key::any()]) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Unregister multiple Key items of a given type and scope.
|
|
|
|
|
|
+
|
|
|
This function is usually more efficient than calling [`unreg/1`](#unreg-1)
|
|
|
-repeatedly.<a name="nb_wait-1"></a>
|
|
|
+repeatedly.
|
|
|
+<a name="nb_wait-1"></a>
|
|
|
|
|
|
-###nb_wait/1##
|
|
|
+### nb_wait/1 ###
|
|
|
|
|
|
|
|
|
-<pre>nb_wait(Key::<a href="#type-key">key()</a>) -> Ref</pre>
|
|
|
+<pre><code>
|
|
|
+nb_wait(Key::<a href="#type-key">key()</a>) -> Ref
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
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.<a name="nb_wait-2"></a>
|
|
|
+{gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.
|
|
|
+<a name="nb_wait-2"></a>
|
|
|
+
|
|
|
+### nb_wait/2 ###
|
|
|
|
|
|
-###nb_wait/2##
|
|
|
|
|
|
+<pre><code>
|
|
|
+nb_wait(Node::node(), Key::<a href="#type-key">key()</a>) -> Ref
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>nb_wait(Node::node(), Key::<a href="#type-key">key()</a>) -> Ref</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
Wait for a local name to be registered on `Node`.
|
|
|
The caller can expect to receive a message,
|
|
|
-{gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.<a name="next-2"></a>
|
|
|
+{gproc, Ref, registered, {Key, Pid, Value}}, once the name is registered.
|
|
|
+<a name="next-2"></a>
|
|
|
|
|
|
-###next/2##
|
|
|
+### next/2 ###
|
|
|
|
|
|
|
|
|
-<pre>next(Context::<a href="#type-context">context()</a>, Key::<a href="#type-key">key()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'</pre>
|
|
|
+<pre><code>
|
|
|
+next(Context::<a href="#type-context">context()</a>, Key::<a href="#type-key">key()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
+Behaves as ets:next(Tab,Key) for a given type of registration.
|
|
|
|
|
|
-Behaves as ets:next(Tab,Key) for a given type of registration object.
|
|
|
|
|
|
See [`http://www.erlang.org/doc/man/ets.html#next-2`](http://www.erlang.org/doc/man/ets.html#next-2).
|
|
|
-The registry behaves as an ordered_set table.<a name="prev-2"></a>
|
|
|
+The registry behaves as an ordered_set table.
|
|
|
+<a name="prev-2"></a>
|
|
|
+
|
|
|
+### prev/2 ###
|
|
|
|
|
|
-###prev/2##
|
|
|
|
|
|
+<pre><code>
|
|
|
+prev(Context::<a href="#type-context">context()</a>, Key::<a href="#type-key">key()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>prev(Context::<a href="#type-context">context()</a>, Key::<a href="#type-key">key()</a>) -> <a href="#type-key">key()</a> | '$end_of_table'</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
+Behaves as ets:prev(Tab,Key) for a given type of registration.
|
|
|
|
|
|
-Behaves as ets:prev(Tab,Key) for a given type of registration object.
|
|
|
|
|
|
See [`http://www.erlang.org/doc/man/ets.html#prev-2`](http://www.erlang.org/doc/man/ets.html#prev-2).
|
|
|
-The registry behaves as an ordered_set table.<a name="reg-1"></a>
|
|
|
+The registry behaves as an ordered_set table.
|
|
|
+<a name="reg-1"></a>
|
|
|
|
|
|
-###reg/1##
|
|
|
+### reg/1 ###
|
|
|
|
|
|
|
|
|
-<pre>reg(Key::<a href="#type-key">key()</a>) -> true</pre>
|
|
|
+<pre><code>
|
|
|
+reg(Key::<a href="#type-key">key()</a>) -> true
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`reg(Key, default(Key))`](#reg-2).<a name="reg-2"></a>
|
|
|
+Equivalent to [`reg(Key, default(Key))`](#reg-2).
|
|
|
+<a name="reg-2"></a>
|
|
|
|
|
|
-###reg/2##
|
|
|
+### reg/2 ###
|
|
|
|
|
|
|
|
|
-<pre>reg(Key::<a href="#type-key">key()</a>, Value) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+reg(Key::<a href="#type-key">key()</a>, Value) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Register a name or property for the current process
|
|
|
|
|
|
+
|
|
|
+
|
|
|
<a name="reg_or_locate-1"></a>
|
|
|
|
|
|
-###reg_or_locate/1##
|
|
|
+### reg_or_locate/1 ###
|
|
|
+
|
|
|
|
|
|
+<pre><code>
|
|
|
+reg_or_locate(Key::<a href="#type-key">key()</a>) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>reg_or_locate(Key::<a href="#type-key">key()</a>) -> true</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`reg_or_locate(Key, default(Key))`](#reg_or_locate-2).<a name="reg_or_locate-2"></a>
|
|
|
+Equivalent to [`reg_or_locate(Key, default(Key))`](#reg_or_locate-2).
|
|
|
+<a name="reg_or_locate-2"></a>
|
|
|
|
|
|
-###reg_or_locate/2##
|
|
|
+### reg_or_locate/2 ###
|
|
|
|
|
|
|
|
|
-<pre>reg_or_locate(Key::<a href="#type-key">key()</a>, Value) -> {pid(), NewValue}</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+reg_or_locate(Key::<a href="#type-key">key()</a>, Value) -> {pid(), NewValue}
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Try registering a unique name, or return existing registration.
|
|
|
|
|
|
+
|
|
|
This function tries to register the name `Key`, if available.
|
|
|
-If such a registration already exists, the pid and value of
|
|
|
-the current registration is returned instead.<a name="reg_or_locate-3"></a>
|
|
|
+If such a registration object already exists, the pid and value of
|
|
|
+the current registration is returned instead.
|
|
|
+<a name="reg_or_locate-3"></a>
|
|
|
|
|
|
-###reg_or_locate/3##
|
|
|
+### reg_or_locate/3 ###
|
|
|
|
|
|
|
|
|
-<pre>reg_or_locate(Key::<a href="#type-key">key()</a>, Value, Fun::function()) -> {pid(), NewValue}</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+reg_or_locate(Key::<a href="#type-key">key()</a>, Value, Fun::function()) -> {pid(), NewValue}
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -948,30 +1278,38 @@ 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.
|
|
|
|
|
|
+
|
|
|
This function is only available for local registration. While it could
|
|
|
theoretically be done in the global case, the spawning of a new process
|
|
|
-on a remote node by the leader instance is more problematic.<a name="reg_shared-1"></a>
|
|
|
+on a remote node by the leader instance is more problematic.
|
|
|
+<a name="reg_shared-1"></a>
|
|
|
|
|
|
-###reg_shared/1##
|
|
|
+### reg_shared/1 ###
|
|
|
|
|
|
|
|
|
-<pre>reg_shared(Key::<a href="#type-key">key()</a>) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+reg_shared(Key::<a href="#type-key">key()</a>) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Register a resource, but don't tie it to a particular process.
|
|
|
|
|
|
+
|
|
|
`reg_shared({c,l,C}) -> reg_shared({c,l,C}, 0).`
|
|
|
-`reg_shared({a,l,A}) -> reg_shared({a,l,A}, undefined).`<a name="reg_shared-2"></a>
|
|
|
+`reg_shared({a,l,A}) -> reg_shared({a,l,A}, undefined).`
|
|
|
+<a name="reg_shared-2"></a>
|
|
|
|
|
|
-###reg_shared/2##
|
|
|
+### reg_shared/2 ###
|
|
|
|
|
|
|
|
|
-<pre>reg_shared(Key::<a href="#type-key">key()</a>, Value) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+reg_shared(Key::<a href="#type-key">key()</a>, Value) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -983,42 +1321,54 @@ Shared resources are all unique. They remain until explicitly unregistered
|
|
|
(using [`unreg_shared/1`](#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}, 1, shared) would
|
|
|
+`Pid == shared`. To wit, update_counter({c,l,myCounter}, shared, 1) would
|
|
|
increment the shared counter `myCounter` with 1, provided it exists.
|
|
|
|
|
|
+
|
|
|
A shared aggregated counter will track updates in exactly the same way as
|
|
|
-an aggregated counter which is owned by a process.<a name="register_name-2"></a>
|
|
|
+an aggregated counter which is owned by a process.
|
|
|
+<a name="register_name-2"></a>
|
|
|
+
|
|
|
+### register_name/2 ###
|
|
|
|
|
|
-###register_name/2##
|
|
|
|
|
|
+<pre><code>
|
|
|
+register_name(Name::<a href="#type-key">key()</a>, Pid::pid()) -> yes | no
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>register_name(Name::<a href="#type-key">key()</a>, Pid::pid()) -> yes | no</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Behaviour support callback<a name="reset_counter-1"></a>
|
|
|
+Behaviour support callback
|
|
|
+<a name="reset_counter-1"></a>
|
|
|
|
|
|
-###reset_counter/1##
|
|
|
+### reset_counter/1 ###
|
|
|
|
|
|
|
|
|
-<pre>reset_counter(Key) -> {ValueBefore, ValueAfter}</pre>
|
|
|
-<ul class="definitions"><li><pre>Key = {c, Scope, Name}</pre></li><li><pre>Scope = l | g</pre></li><li><pre>ValueBefore = integer()</pre></li><li><pre>ValueAfter = integer()</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+reset_counter(Key) -> {ValueBefore, ValueAfter}
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Key = {c, Scope, Name}</code></li><li><code>Scope = l | g</code></li><li><code>ValueBefore = integer()</code></li><li><code>ValueAfter = integer()</code></li></ul>
|
|
|
|
|
|
|
|
|
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`](#update_counter-2),
|
|
|
which allows for concurrent calls to [`update_counter/2`](#update_counter-2) without losing
|
|
|
-updates. Aggregated counters are updated accordingly.<a name="select-1"></a>
|
|
|
+updates. Aggregated counters are updated accordingly.
|
|
|
+<a name="select-1"></a>
|
|
|
|
|
|
-###select/1##
|
|
|
+### select/1 ###
|
|
|
|
|
|
|
|
|
-<pre>select(Continuation::Arg) -> [Match] | {[Match], Continuation} | '$end_of_table'</pre>
|
|
|
-<ul class="definitions"><li><pre>Arg = Continuation | <a href="#type-sel_pattern">sel_pattern()</a></pre></li><li><pre>Match = {Key, Pid, Value}</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+select(Continuation::Arg) -> [Match] | {[Match], Continuation} | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Arg = Continuation | <a href="#type-sel_pattern">sel_pattern()</a></code></li><li><code>Match = {Key, Pid, Value}</code></li></ul>
|
|
|
|
|
|
|
|
|
Perform a select operation on the process registry
|
|
|
@@ -1041,17 +1391,21 @@ 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.
|
|
|
|
|
|
+
|
|
|
The physical representation in the registry may differ from the above,
|
|
|
but the select patterns are transformed appropriately. The logical
|
|
|
representation for the gproc select operations is given by
|
|
|
-<code><a href="#type-headpat">headpat()</a></code>.<a name="select-2"></a>
|
|
|
+<code><a href="#type-headpat">headpat()</a></code>.
|
|
|
+<a name="select-2"></a>
|
|
|
|
|
|
-###select/2##
|
|
|
+### select/2 ###
|
|
|
|
|
|
|
|
|
-<pre>select(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [{Key, Pid, Value}]</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+select(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [{Key, Pid, Value}]
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -1062,6 +1416,7 @@ 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.
|
|
|
|
|
|
+
|
|
|
Note that limiting the context is just a convenience function, allowing you
|
|
|
to write a simpler select pattern and still avoid searching the entire
|
|
|
registry. Whenever variables are used in the head pattern, this will result
|
|
|
@@ -1069,66 +1424,131 @@ in a wider scan, even if the values are restricted through a guard (e.g.
|
|
|
`select([{'$1','$2','$3'}, [{'==', '$1', p}], ...])` will count as a wild
|
|
|
pattern on the key and result in a full scan). In this case, specifying a
|
|
|
Context will allow gproc to perform some variable substitution and ensure
|
|
|
-that the scan is limited.<a name="select-3"></a>
|
|
|
+that the scan is limited.
|
|
|
+<a name="select-3"></a>
|
|
|
|
|
|
-###select/3##
|
|
|
+### select/3 ###
|
|
|
|
|
|
|
|
|
-<pre>select(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_patten">sel_patten()</a>, Limit::integer()) -> {[Match], Continuation} | '$end_of_table'</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+select(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_patten">sel_patten()</a>, Limit::integer()) -> {[Match], Continuation} | '$end_of_table'
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Like [`select/2`](#select-2) but returns Limit objects at a time.
|
|
|
|
|
|
-See [`http://www.erlang.org/doc/man/ets.html#select-3`](http://www.erlang.org/doc/man/ets.html#select-3).<a name="select_count-1"></a>
|
|
|
|
|
|
-###select_count/1##
|
|
|
+See [`http://www.erlang.org/doc/man/ets.html#select-3`](http://www.erlang.org/doc/man/ets.html#select-3).
|
|
|
+<a name="select_count-1"></a>
|
|
|
+
|
|
|
+### select_count/1 ###
|
|
|
+
|
|
|
|
|
|
+<pre><code>
|
|
|
+select_count(Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [<a href="#type-sel_object">sel_object()</a>]
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>select_count(Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [<a href="#type-sel_object">sel_object()</a>]</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`select_count(all, Pat)`](#select_count-2).<a name="select_count-2"></a>
|
|
|
+Equivalent to [`select_count(all, Pat)`](#select_count-2).
|
|
|
+<a name="select_count-2"></a>
|
|
|
|
|
|
-###select_count/2##
|
|
|
+### select_count/2 ###
|
|
|
|
|
|
|
|
|
-<pre>select_count(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [{Key, Pid, Value}]</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+select_count(Context::<a href="#type-context">context()</a>, Pat::<a href="#type-sel_pattern">sel_pattern()</a>) -> [{Key, Pid, Value}]
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
Perform a select_count operation on the process registry.
|
|
|
|
|
|
+
|
|
|
The physical representation in the registry may differ from the above,
|
|
|
-but the select patterns are transformed appropriately.<a name="send-2"></a>
|
|
|
+but the select patterns are transformed appropriately.
|
|
|
+<a name="send-2"></a>
|
|
|
|
|
|
-###send/2##
|
|
|
+### send/2 ###
|
|
|
|
|
|
|
|
|
-<pre>send(Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+send(Key::<a href="#type-key">key()</a>, Msg::any()) -> Msg
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
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.<a name="set_env-5"></a>
|
|
|
+property), Msg will be send to all processes that have such an object.
|
|
|
+<a name="set_attributes-2"></a>
|
|
|
+
|
|
|
+### set_attributes/2 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+set_attributes(Key::<a href="#type-key">key()</a>, Props::[{atom(), any()}]) -> true
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
|
|
|
-###set_env/5##
|
|
|
+Add/modify `{Key, Value}` attributes associated with a registration.
|
|
|
|
|
|
|
|
|
-<pre>set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Value::term(), Strategy) -> Value</pre>
|
|
|
-<ul class="definitions"><li><pre>Strategy = [Alternative]</pre></li><li><pre>Alternative = app_env | os_env | {os_env, VAR} | {mnesia, ActivityType, Oid, Pos}</pre></li></ul>
|
|
|
|
|
|
+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.
|
|
|
+
|
|
|
+
|
|
|
+Attributs can be retrieved using `gproc:get_attribute/3` or
|
|
|
+`gproc:get_attributes/2`.
|
|
|
+<a name="set_attributes_shared-2"></a>
|
|
|
+
|
|
|
+### set_attributes_shared/2 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+set_attributes_shared(Key::<a href="#type-key">key()</a>, Props::[{K, V}]) -> true
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+
|
|
|
+Attributes can be retrieved using `gproc:get_attribute/3` or
|
|
|
+`gproc:get_attributes/2`.
|
|
|
+<a name="set_env-5"></a>
|
|
|
+
|
|
|
+### set_env/5 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+set_env(Scope::<a href="#type-scope">scope()</a>, App::atom(), Key::atom(), Value::term(), Strategy) -> Value
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<ul class="definitions"><li><code>Strategy = [Alternative]</code></li><li><code>Alternative = app_env | os_env | {os_env, VAR} | {mnesia, ActivityType, Oid, Pos}</code></li></ul>
|
|
|
|
|
|
|
|
|
Updates the cached value as well as underlying environment.
|
|
|
@@ -1140,68 +1560,111 @@ environment outside gproc. This function modifies the cached value, and then
|
|
|
proceeds to update the underlying environment (OS environment variable or
|
|
|
application environment variable).
|
|
|
|
|
|
+
|
|
|
When the `mnesia` alternative is used, gproc will try to update any existing
|
|
|
object, changing only the `Pos` position. If no such object exists, it will
|
|
|
create a new object, setting any other attributes (except `Pos` and the key)
|
|
|
-to `undefined`.<a name="set_value-2"></a>
|
|
|
+to `undefined`.
|
|
|
+<a name="set_value-2"></a>
|
|
|
|
|
|
-###set_value/2##
|
|
|
+### set_value/2 ###
|
|
|
|
|
|
|
|
|
-<pre>set_value(Key::<a href="#type-key">key()</a>, Value) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+set_value(Key::<a href="#type-key">key()</a>, Value) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
-Sets the value of the registeration entry given by Key
|
|
|
+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.
|
|
|
|
|
|
+
|
|
|
Value can be any term, unless the object is a counter, in which case
|
|
|
-it must be an integer.<a name="start_link-0"></a>
|
|
|
+it must be an integer.
|
|
|
+<a name="set_value_shared-2"></a>
|
|
|
+
|
|
|
+### set_value_shared/2 ###
|
|
|
|
|
|
-###start_link/0##
|
|
|
|
|
|
+<pre><code>
|
|
|
+set_value_shared(Key::<a href="#type-key">key()</a>, Value) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>start_link() -> {ok, pid()}</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
+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.
|
|
|
+
|
|
|
+
|
|
|
+Value can be any term, unless the object is a counter, in which case
|
|
|
+it must be an integer.
|
|
|
+<a name="start_link-0"></a>
|
|
|
+
|
|
|
+### start_link/0 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+start_link() -> {ok, pid()}
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
+
|
|
|
+
|
|
|
|
|
|
Starts the gproc server.
|
|
|
|
|
|
+
|
|
|
This function is intended to be called from gproc_sup, as part of
|
|
|
-starting the gproc application.<a name="table-0"></a>
|
|
|
+starting the gproc application.
|
|
|
+<a name="table-0"></a>
|
|
|
|
|
|
-###table/0##
|
|
|
+### table/0 ###
|
|
|
|
|
|
|
|
|
-<pre>table() -> any()</pre>
|
|
|
+<pre><code>
|
|
|
+table() -> any()
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`table({all, all})`](#table-1).<a name="table-1"></a>
|
|
|
+Equivalent to [`table({all, all})`](#table-1).
|
|
|
+<a name="table-1"></a>
|
|
|
+
|
|
|
+### table/1 ###
|
|
|
|
|
|
-###table/1##
|
|
|
|
|
|
+<pre><code>
|
|
|
+table(Context::<a href="#type-context">context()</a>) -> any()
|
|
|
+</code></pre>
|
|
|
|
|
|
-<pre>table(Context::<a href="#type-context">context()</a>) -> any()</pre>
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Equivalent to [`table(Context, [])`](#table-2).<a name="table-2"></a>
|
|
|
+Equivalent to [`table(Context, [])`](#table-2).
|
|
|
+<a name="table-2"></a>
|
|
|
|
|
|
-###table/2##
|
|
|
+### table/2 ###
|
|
|
|
|
|
|
|
|
-<pre>table(Context::<a href="#type-context">context()</a>, Opts) -> any()</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+table(Context::<a href="#type-context">context()</a>, Opts) -> any()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -1209,6 +1672,7 @@ 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`](http://www.erlang.org/doc/man/qlc.html).
|
|
|
|
|
|
+
|
|
|
NOTE: By default, the gproc table generator will not filter out entries
|
|
|
belonging to processes that have just died, but which have yet to be cleared
|
|
|
out of the registry. Use the option `check_pids` (or `{check_pids, true}`)
|
|
|
@@ -1216,39 +1680,50 @@ if you want to filter out dead entries already in the query. There will be
|
|
|
some overhead associated with doing so, and given that the process monitoring
|
|
|
is asynchronous, there can never be any guarantee that there are no dead
|
|
|
entries in the list by the time your program processes it.
|
|
|
+
|
|
|
<a name="unreg-1"></a>
|
|
|
|
|
|
-###unreg/1##
|
|
|
+### unreg/1 ###
|
|
|
|
|
|
|
|
|
-<pre>unreg(Key::<a href="#type-key">key()</a>) -> true</pre>
|
|
|
+<pre><code>
|
|
|
+unreg(Key::<a href="#type-key">key()</a>) -> true
|
|
|
+</code></pre>
|
|
|
+
|
|
|
<br></br>
|
|
|
|
|
|
|
|
|
-Unregister a name or property.<a name="unreg_shared-1"></a>
|
|
|
+Unregister a name or property.
|
|
|
+<a name="unreg_shared-1"></a>
|
|
|
|
|
|
-###unreg_shared/1##
|
|
|
+### unreg_shared/1 ###
|
|
|
|
|
|
|
|
|
-<pre>unreg_shared(Key::<a href="#type-key">key()</a>) -> true</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+unreg_shared(Key::<a href="#type-key">key()</a>) -> true
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
-Unregister a shared resource.<a name="unregister_name-1"></a>
|
|
|
|
|
|
-###unregister_name/1##
|
|
|
+Unregister a shared resource.
|
|
|
+<a name="unregister_name-1"></a>
|
|
|
|
|
|
+### unregister_name/1 ###
|
|
|
|
|
|
`unregister_name(Key) -> any()`
|
|
|
|
|
|
-Equivalent to `unreg / 1`.<a name="update_counter-2"></a>
|
|
|
+Equivalent to `unreg / 1`.
|
|
|
+<a name="update_counter-2"></a>
|
|
|
|
|
|
-###update_counter/2##
|
|
|
+### update_counter/2 ###
|
|
|
|
|
|
|
|
|
-<pre>update_counter(Key::<a href="#type-key">key()</a>, Incr::<a href="#type-increment">increment()</a>) -> integer()</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+update_counter(Key::<a href="#type-key">key()</a>, Incr::<a href="#type-increment">increment()</a>) -> integer()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -1258,18 +1733,39 @@ 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`](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.
|
|
|
+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`.<a name="update_counters-2"></a>
|
|
|
+that the position is omitted; in gproc, the value position is always `3`.
|
|
|
|
|
|
-###update_counters/2##
|
|
|
|
|
|
+If `Key` refers to a unique name, the operation will depend on the value
|
|
|
+part of the registration being an integer(). While non-integer values are
|
|
|
+not permitted at all for counter objects, it is the user's responsibility to
|
|
|
+ensure that a name, on which `update_counter/2` is to be performed, has the
|
|
|
+appropriate value type.
|
|
|
+<a name="update_counter-3"></a>
|
|
|
+
|
|
|
+### update_counter/3 ###
|
|
|
+
|
|
|
+`update_counter(Key, Pid, Incr) -> any()`
|
|
|
|
|
|
-<pre>update_counters(X1::<a href="#type-scope">scope()</a>, Cs::[{<a href="#type-key">key()</a>, pid(), <a href="#type-increment">increment()</a>}]) -> [{<a href="#type-key">key()</a>, pid(), integer()}]</pre>
|
|
|
-<br></br>
|
|
|
|
|
|
+<a name="update_counters-2"></a>
|
|
|
+
|
|
|
+### update_counters/2 ###
|
|
|
+
|
|
|
+
|
|
|
+<pre><code>
|
|
|
+update_counters(X1::<a href="#type-scope">scope()</a>, Cs::[{<a href="#type-key">key()</a>, pid(), <a href="#type-increment">increment()</a>}]) -> [{<a href="#type-key">key()</a>, pid(), integer()}]
|
|
|
+</code></pre>
|
|
|
+
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
@@ -1281,14 +1777,18 @@ This function is not atomic, except (in a sense) for global counters. For local
|
|
|
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.
|
|
|
|
|
|
-The return value is the corresponding list of `[{Counter, Pid, NewValue}]`.<a name="update_shared_counter-2"></a>
|
|
|
|
|
|
-###update_shared_counter/2##
|
|
|
+The return value is the corresponding list of `[{Counter, Pid, NewValue}]`.
|
|
|
+<a name="update_shared_counter-2"></a>
|
|
|
+
|
|
|
+### update_shared_counter/2 ###
|
|
|
|
|
|
|
|
|
-<pre>update_shared_counter(Key::<a href="#type-key">key()</a>, Incr) -> integer() | [integer()]</pre>
|
|
|
-<ul class="definitions"><li><pre>Incr = IncrVal | UpdateOp | [UpdateOp]</pre></li><li><pre>UpdateOp = IncrVal | {IncrVal, Threshold, SetValue}</pre></li><li><pre>IncrVal = integer()</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+update_shared_counter(Key::<a href="#type-key">key()</a>, Incr) -> integer() | [integer()]
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Incr = IncrVal | UpdateOp | [UpdateOp]</code></li><li><code>UpdateOp = IncrVal | {IncrVal, Threshold, SetValue}</code></li><li><code>IncrVal = integer()</code></li></ul>
|
|
|
|
|
|
|
|
|
Updates the shared counter registered as Key.
|
|
|
@@ -1299,38 +1799,46 @@ This function works almost exactly like ets:update_counter/3
|
|
|
(see [`http://www.erlang.org/doc/man/ets.html#update_counter-3`](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.
|
|
|
|
|
|
+
|
|
|
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`.<a name="where-1"></a>
|
|
|
+that the position is omitted; in gproc, the value position is always `3`.
|
|
|
+<a name="where-1"></a>
|
|
|
|
|
|
-###where/1##
|
|
|
+### where/1 ###
|
|
|
|
|
|
|
|
|
-<pre>where(Key::<a href="#type-key">key()</a>) -> pid()</pre>
|
|
|
-<br></br>
|
|
|
+<pre><code>
|
|
|
+where(Key::<a href="#type-key">key()</a>) -> pid()
|
|
|
+</code></pre>
|
|
|
|
|
|
+<br></br>
|
|
|
|
|
|
|
|
|
|
|
|
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`](#lookup_pids-1) in these
|
|
|
-cases.<a name="whereis_name-1"></a>
|
|
|
|
|
|
-###whereis_name/1##
|
|
|
+The type of registration must be either name or aggregated counter.
|
|
|
+Otherwise this function will exit. Use [`lookup_pids/1`](#lookup_pids-1) in these
|
|
|
+cases.
|
|
|
+<a name="whereis_name-1"></a>
|
|
|
|
|
|
+### whereis_name/1 ###
|
|
|
|
|
|
`whereis_name(Key) -> any()`
|
|
|
|
|
|
-Equivalent to `where / 1`.<a name="wide_await-3"></a>
|
|
|
+Equivalent to `where / 1`.
|
|
|
+<a name="wide_await-3"></a>
|
|
|
|
|
|
-###wide_await/3##
|
|
|
+### wide_await/3 ###
|
|
|
|
|
|
|
|
|
-<pre>wide_await(Nodes::[node()], Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}</pre>
|
|
|
-<ul class="definitions"><li><pre>Timeout = integer() | infinity</pre></li></ul>
|
|
|
+<pre><code>
|
|
|
+wide_await(Nodes::[node()], Key::<a href="#type-key">key()</a>, Timeout) -> {pid(), Value}
|
|
|
+</code></pre>
|
|
|
|
|
|
+<ul class="definitions"><li><code>Timeout = integer() | infinity</code></li></ul>
|
|
|
|
|
|
|
|
|
Wait for a local name to be registered on any of `Nodes`.
|
|
|
@@ -1339,5 +1847,6 @@ 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}`.
|
|
|
|
|
|
+
|
|
|
An exception is thrown upon timeout, or if no node can be reached (if gproc is
|
|
|
-not running on a given node, this is treated the same as the node being down).
|
|
|
+not running on a given node, this is treated the same as the node being down).
|
Ulf Wiger