forked from erlware/resource_discovery
-
Notifications
You must be signed in to change notification settings - Fork 0
/
overview.edoc
167 lines (132 loc) · 7.49 KB
/
overview.edoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
@title The Resource Discovery Application
@doc
<p>
The Resource Discovery application allows you to set up smart Erlang clusters. Producers and consumers within an Erlang cluster can find eachother with no pre-configuration needed. For example lets say we have three services in a cluster of nodes:
</p>
<ul>
<li>Video Display Agent</li>
<li>Video Producer</li>
<li>System Logger</li>
</ul>
<p>
The Display Agent must of course be able to find a Video Producer and both the Video Producer and the Display Agent must know about the system logger. Before understanding how all that is expressed in Resource Discovery we need to get some definitions out of the way.
</p>
<h2>Definitions</h2>
<p>
Resource Discovery has 3 major types that you need to be concerned with. They are listed here.
</p>
<p>
resource_tuple() = {resource_type(), resource()}. The type
of a resource followed by the actual resource. Local
resource tuples are communicated to other resource discovery
instances.
</p>
<p>
resource_type() = atom(). The name of a resource, how it is identified. For example
a type of service that you have on the network may be identified by it's node name
in which case you might have a resource type of 'my_service' of which there may be
many node names representing resources such as {my_service, myservicenode@myhost}.
</p>
<p>
resource() = term(). Either a concrete resource or a reference to one like a pid().
</p>
<h2>Expressing Relationships</h2>
<p>
Using these definitions we can describe the relationships that we have between our different services; the Video Display Agent, the Video Producer, and the System Logger. It is helpful to break things down into three categories. These are as follows:
</p>
<ul>
<li>Local Resources Tuples</li>
<li>Target Resource Types</li>
<li>Cached Resource Tuples</li>
</ul>
<p>
Local Resources Tuples contain those resources that a running Erlang node has to share with the cluster. A Video Display Agent node could make a call like what is below to express what it has to share with the network.
</p>
```
resource_discovery:add_local_resource_tuples({video_producer, node()}).
'''
<p>
A Video Producer node needs to know about the System Logger instance and about all instances of Video Display Agent nodes. To express this it could make a call like what is below to express this.
</p>
```
resource_discovery:add_target_resource_types([video_display, system_logger]).
'''
<p>
This indicates that the Video Producer service wants to find out about all services in the cluster of resource types video_display and system_logger.
</p>
<p>
Now we are set up for our system to obtain resource tuples from other nodes in the cluster and cache them locally. Cached Resource Tuples are those that have been discovered and are ready to be used. When each of the nodes comes up onto the network they will make one of the following calls:
</p>
```
resource_discovery:trade_resources().
'''
or
```
resource_discovery:sync_resources().
'''
<p>
This will communicate with all other nodes in the current network. When this function returns all Resource Tuples on the network that match the calling nodes Target Resource Types will be cached locally. Furthermore the local nodes Local Resource Tuples will be cached on all remote nodes that have specified their resource types as target resource types. trade_resources/0 accomplishes this asyncronously where as sync_resources is a blocking call which typically accomplishes a full sync before returning. After either of these calls have been made you can go about using the resources you have discovered.
</p>
<p>
To use a resource from the resource cache Resource Discovery provides a number of useful functions. The most common of these is ``get_resource/1''. This will loop through resources in round robin fashion supplying a different resource each time it is called. There are also the rpc functions that act upon node based resources; these are rpc_call and rpc_multicall. There are other functions available for more control over the specific resources of a particular type you get. There are also functions provided for removing resources that have been found to be malfunctioning or simply not around anymore. This is up to the user of resource discovery to do at the application level.
</p>
<h2>Getting Notifications about New Resources</h2>
<p>
Sometimes when resources become available in the cluster it is desirable for an application to be notified of their presence. If you want immediate notification of new Cached Resources you can subscribe to notifications by using:
</p>
```
resource_discovery:add_callback_modules([video_send, log_send]).
'''
<p>
The above call will ensure that the exported function "resource_up/1" will be called upon the caching of a new resource within the modules "video_send" and "log_send". Those functions will be called each time this happens regardless of the resource and so the resource up function should use pattern matching like that pictured below to only concern itself with the resources it needs to act upon.
</p>
```
resource_up({system_logger, Instance}) ->
... do stuff ...
resource_up(_DontCare) ->
ok.
'''
<h2>Getting into an Erlang Cloud</h2>
<p>
Getting into an Erlang node cluster is required as a minimal bootstrap for Resource Discovery. To accomplish initial contact by pinging remote nodes already in the desired cloud the following entries should be in your Erlang config file.
</p>
```
{resource_discovery,
[
{contact_nodes, [[email protected], [email protected]]}
]
}
'''
<p>
These entries instruct resource discovery to ping node1 and node2 in order to join an Erlang cloud. At least one of the pings must succeed in order for startup to succeed. Optionally all this can be overridden at the command line with the -contact_node flag:
</p>
```
erl ... -contact_node [email protected]
'''
<p>
The above flag set at startup would instruct Resource Discovery to ping node3 instead of those configured in the config file. In the future a plugin scheme will be added so that other methods of bootstrapping into a cloud may be added. An easy way to get up and running for a test is to fire up the first node pointing to itself and then additional nodes pointing to the first as in the following example: (remember that "Macintosh" should be replaced with your local sname suffix)
</p>
```
erl -sname a -contact_node a@Macintosh
erl -sname b -contact_node a@Macintosh
erl -sname c -contact_node a@Macintosh
'''
<h2>Overcomming network and resource failures with heartbeating</h2>
<p>
At times resources fail and are perhaps taken out of the store of Cached Resource Tuples by an application when it discovers the resource is no longer around. At other times networks may fail and clusters become separated. One way of overcomming all of this is to setup heartbeats from Resource Discovery. Resource discovery can be configured to heartbeat at a specified interval. This means that it will both re-ping the configured contact nodes and will run a trade_resources/0 at the specified interval. To enable this place configuration similar to what is below in you Erlang config file.
</p>
```
{resource_discovery,
[
{heartbeat_frequency, 60000}
]
}
'''
<p>
An entry like that above tells Resource Discovery to ping about every 60000 milliseconds plus or minus a randomization factor. An entry of 0 disables heartbeating all together and is the default if not configured.
</p>
<p>
Enjoy! Send questions of comments to [email protected] or [email protected].
</p>
@author Martin Logan <[email protected]>
@copyright 2010 Erlware