Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 141 lines (62 sloc) 4.123 kb
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
1
2
3 <h1>The gproc application</h1>
4
5 The gproc application
6 =====================
7 Extended process dictionary.
8
9 __Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)), Joseph Wayne Norton ([`norton@geminimobile.com`](mailto:norton@geminimobile.com)).
10
11 Extended process dictionary
12
13
14
af14ad2 doc additions, inherit by name, init_arg
Ulf Wiger authored
15 <h2>Introduction</h2>
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
16
17
18
19
98ba2d9 added rebar support
Ulf Wiger authored
20
21 Gproc is a process dictionary for Erlang, which provides a number of useful features beyond what the built-in dictionary has:
22
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
23
98ba2d9 added rebar support
Ulf Wiger authored
24 * Use any term as a process alias
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
25
98ba2d9 added rebar support
Ulf Wiger authored
26 * Register a process under several aliases
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
27
98ba2d9 added rebar support
Ulf Wiger authored
28 * Non-unique properties can be registered simultaneously by many processes
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
29
98ba2d9 added rebar support
Ulf Wiger authored
30 * QLC and match specification interface for efficient queries on the
31 dictionary
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
32
98ba2d9 added rebar support
Ulf Wiger authored
33 * Await registration, let's you wait until a process registers itself
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
34
35 * Atomically give away registered names and properties to another process
36
98ba2d9 added rebar support
Ulf Wiger authored
37 * Counters, and aggregated counters, which automatically maintain the
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
38 total of all counters with a given name
39
40 * Global registry, with all the above functions applied to a network of nodes
41
42
43
44
45
af14ad2 doc additions, inherit by name, init_arg
Ulf Wiger authored
46 <h3>Use case: System inspection</h3>
47
48
49
50
51
52 Gproc was designed to work as a central index for "process metadata", i.e.
53 properties that describe the role and characteristics of each process. Having
54 a single registry that is flexible enough to hold important types of property
55 makes it easier to (a) find processes of a certain type, and (b) query and
56 browse key data in a running system.
57
58
59
60 <h3>Use case: Pub/Sub patterns</h3>
61
62
63
64
65
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
66 An interesting application of gproc is building publish/subscribe patterns.
67 Example:
68
69 <pre>
59365c4 Fixed select/qlc scope (default: all); fixed dist eunit test; new rebar
Ulf Wiger authored
70 subscribe(EventType) ->
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
71 %% Gproc notation: {p, l, Name} means {(p)roperty, (l)ocal, Name}
72 gproc:reg({p, l, {?MODULE, EventType}}).
73
59365c4 Fixed select/qlc scope (default: all); fixed dist eunit test; new rebar
Ulf Wiger authored
74 notify(EventType, Msg) ->
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
75 Key = {?MODULE, EventType},
76 gproc:send({p, l, Key}, {self(), Key, Msg}).
77 </pre>
78
79
80
af14ad2 doc additions, inherit by name, init_arg
Ulf Wiger authored
81 <h3>Use case: Environment handling</h3>
82
83
84
85
86
87 Gproc provides a set of functions to read environment variables, possibly from
88 alternative sources, and cache them for efficient lookup. Caching also provides
89 a way to see which processes rely on certain configuration values, as well as
90 which values they actually ended up using.
91
92
93
781e0d0 norton chgs merged, version 0.2.11
Ulf Wiger authored
94 See [`gproc:get_env/4`](http://github.com/esl/gproc/blob/master/doc/gproc.md#get_env-4), [`gproc:get_set_env/4`](http://github.com/esl/gproc/blob/master/doc/gproc.md#get_set_env-4) and
95 [`gproc:set_env/5`](http://github.com/esl/gproc/blob/master/doc/gproc.md#set_env-5) for details.
af14ad2 doc additions, inherit by name, init_arg
Ulf Wiger authored
96
97
98
99 <h2>Testing</h2>
100
101
102
103
104
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
105 Gproc has a QuickCheck test suite, covering a fairly large part of the local
106 gproc functionality, although none of the global registry. It requires a
107 commercial EQC license, but rebar is smart enough to detect whether EQC is
108 available, and if it isn't, the code in gproc_eqc.erl will be "defined away".
109
110
111
112 There is also an eunit suite, covering the basic operations for local and
113 global gproc.
114
115
116
af14ad2 doc additions, inherit by name, init_arg
Ulf Wiger authored
117 <h2>Building Edoc</h2>
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
118
119
120
121
122 By default, `./rebar doc` generates Github-flavored Markdown files.If you want to change this, remove the `edoc_opts` line from `rebar.config`.
123
124 Gproc was first introduced at the ACM SIGPLAN Erlang Workshop in
781e0d0 norton chgs merged, version 0.2.11
Ulf Wiger authored
125 Freiburg 2007 ([Paper available here](http://github.com/esl/gproc/blob/master/doc/erlang07-wiger.pdf)).
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
126
127
128 <h2 class="indextitle">Modules</h2>
98ba2d9 added rebar support
Ulf Wiger authored
129
130
1cb3c92 added words about building docs
Ulf Wiger authored
131
2393bf4 Added gproc:give_away/2 and introduced eunit tests for gproc_dist
Ulf Wiger authored
132 <table width="100%" border="0" summary="list of modules">
781e0d0 norton chgs merged, version 0.2.11
Ulf Wiger authored
133 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc.md" class="module">gproc</a></td></tr>
134 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_app.md" class="module">gproc_app</a></td></tr>
135 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_dist.md" class="module">gproc_dist</a></td></tr>
b1589f6 Add gproc:i()
Ulf Wiger authored
136 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_info.md" class="module">gproc_info</a></td></tr>
781e0d0 norton chgs merged, version 0.2.11
Ulf Wiger authored
137 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_init.md" class="module">gproc_init</a></td></tr>
138 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_lib.md" class="module">gproc_lib</a></td></tr>
139 <tr><td><a href="http://github.com/esl/gproc/blob/master/doc/gproc_sup.md" class="module">gproc_sup</a></td></tr></table>
1cb3c92 added words about building docs
Ulf Wiger authored
140
Something went wrong with that request. Please try again.